How the Intended-vs-Implemented Skill Audits AI-Built Code

The intended-vs-implemented skill audits AI-built code by comparing documented design claims in /documentation/*.md against concrete enforcement points in the source code, reporting only mismatches that cite both the intent and the implementation gap.

The phuryn/pm-skills repository gives product managers and engineers a disciplined way to validate AI-generated artifacts before release. The intended-vs-implemented skill audits AI-built code by verifying that authorization checks, query filters, and input sanitizers in the source tree actually fulfill the rules written in permissions.md, flows.md, and architecture.md. Unlike conventional linters that only check internal consistency, this skill bridges the gap between documented design intent and working implementation.

How the Skill Audits AI-Built Code

The methodology defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md follows five concrete stages. Only gaps that have both a documented claim and a concrete code artifact (or lack thereof) are reported; pure speculation is filtered out.

1. Collect documented intent. The skill pulls claims from the /documentation/*.md files—for example, permissions.md, architecture.md, and flows.md. Each documented rule becomes a formal intent statement that the code must enforce.

2. Extract implementation evidence. It scans the source tree for concrete enforcement points such as authorization checks, query filters, and input sanitizers. These code fragments are the evidence that a rule is actually realized in the AI-built artifact.

3. Compare intent vs. evidence. The skill builds an intent ↔ code map by matching each documented rule with its corresponding code fragment. This step surfaces where a documented requirement is missing its implementation counterpart.

4. Classify mismatches. Gaps are categorized based on severity. The skill distinguishes matter-changing gaps—those that cross a trust, cost, data, or tenant boundary—from cosmetic drift, ensuring teams prioritize security-relevant findings.

5. Report findings. It produces a structured audit that cites the exact line in the documentation, the exact file and line in the code, the attacker and victim scenario, and a concrete remediation step.

Running the Intended-vs-Implemented Audit

The skill is integrated into the PM-Skills shipping workflow and can be invoked through two primary commands.

Full Shipping Audit

Run the complete pre-release check with:

pm ship-check

According to the workflow defined in pm-ai-shipping/commands/ship-check.md, this command internally executes the security static audit, applying the intended-vs-implemented skill to flag where the code diverges from permissions.md, flows.md, and architecture.md.

Targeted Security Audit

Invoke the skill directly against the documentation files with:

pm security-audit-static

As documented in pm-ai-shipping/commands/security-audit-static.md, this command explicitly applies the intended-vs-implemented skill against /documentation/*.md. A rule documented but not enforced in code is treated as a finding on its own.

Anatomy of an Audit Finding

Findings follow a citation-driven JSON format described in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md. Each entry links a specific claim to its missing or incorrect implementation.

{
  "finding": {
    "intent": "Only admins may delete user accounts (permissions.md, line 12)",
    "implementation": "No check found in `user_service.py` (line -)",
    "attacker": "Authenticated regular user",
    "victim": "All user accounts",
    "remediation": "Add admin-only guard in `delete_user` endpoint"
  }
}

This structure ensures every reported gap references an exact documentation line, a concrete code location or its absence, and a remediation path.

Key Source Files and Architecture

The intended-vs-implemented skill is implemented and wired into the repository through these files:

• pm-ai-shipping/skills/intended-vs-implemented/SKILL.md — Full description of the methodology, scope, and classification rules.
• pm-ai-shipping/commands/ship-check.md — Entry point that runs the skill as part of the overall shipping audit.
• pm-ai-shipping/commands/security-audit-static.md — Direct command that applies the skill against documentation files.
• README.md — High-level summary of the skill within the PM-Skills toolkit.

The architectural flow is straightforward: the user runs pm ship-check, which reads /documentation/*.md for intent, runs the intended-vs-implemented skill to scan the source tree for enforcement points, builds the intent-to-code map, and outputs structured findings. The security-audit-static command incorporates these findings into the final audit report.

Summary

• The intended-vs-implemented skill compares documented claims in /documentation/*.md with concrete enforcement points in the source code.
• It reports only verifiable gaps that pair a documented intent with a specific code artifact or its absence.
• Classifications separate matter-changing security gaps from cosmetic drift.
• The skill is invoked via pm ship-check or pm security-audit-static, as defined in pm-ai-shipping/commands/ship-check.md and pm-ai-shipping/commands/security-audit-static.md.
• Findings use a citation-driven JSON format that cites exact lines in both documentation and code.

Frequently Asked Questions

What makes the intended-vs-implemented skill different from a linter?

Conventional linters check internal code consistency, such as syntax and style. The intended-vs-implemented skill checks whether the code fulfills the original requirements documented in files like permissions.md and architecture.md, bridging the gap between design intent and implementation.

Which documentation files does the skill analyze?

The skill analyzes claims from the /documentation/*.md files, specifically including permissions.md, architecture.md, and flows.md, matching each documented rule against enforcement points in the source code.

Can the skill report a finding if there is no documented rule?

No. The skill filters out pure speculation and "hand-wavy" findings. It only reports gaps where there is both a documented claim and a concrete code artifact (or lack thereof).

How do I run the intended-vs-implemented audit in a CI pipeline?

Run pm ship-check for a full shipping audit that includes the intended-vs-implemented check, or run pm security-audit-static to target the security pass directly. Both commands are defined in pm-ai-shipping/commands/ship-check.md and pm-ai-shipping/commands/security-audit-static.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}