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

> Discover how intended-vs-implemented skill audits AI-built code by comparing documentation claims to source code enforcement. Identify and report design mismatches efficiently.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: deep-dive
- Published: 2026-06-09

---

**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`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md), and [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md), and [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/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:

```bash
pm ship-check

```

According to the workflow defined in [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/flows.md), and [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md).

### Targeted Security Audit

Invoke the skill directly against the documentation files with:

```bash
pm security-audit-static

```

As documented in [`pm-ai-shipping/commands/security-audit-static.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md). Each entry links a specific claim to its missing or incorrect implementation.

```json
{
  "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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md) — Direct command that applies the skill against documentation files.
- [`README.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md) and [`pm-ai-shipping/commands/security-audit-static.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/permissions.md) and [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/permissions.md), [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md), and [`flows.md`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md) and [`pm-ai-shipping/commands/security-audit-static.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md).