Understanding the Intended-vs-Implemented Skill: How to Detect Code-Documentation Gaps

The intended-vs-implemented skill is a systematic audit method that compares documented intent against actual code enforcement to surface security and correctness gaps that traditional linters miss.

The intended-vs-implemented skill is a core component of the phuryn/pm-skills AI Shipping Kit, designed to bridge the gap between architectural documentation and production code. Unlike generic static analysis tools that only verify internal consistency, this skill requires a documented intent first—typically produced by the companion shipping-artifacts skill—then rigorously validates whether the code actually enforces those claims on every execution path.

What Is the Intended-vs-Implemented Skill?

This skill operates as a disciplined comparison engine defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md. It treats documentation files such as architecture.md, flows.md, and permissions.md as the source of truth for system behavior. The audit method then scans the codebase to locate concrete enforcement points, including authorization checks, query filters, and input sanitizers.

According to the phuryn/pm-skills source code, the skill is invoked by command scripts including ship-check, security-audit-static, and derive-tests located in /pm-ai-shipping/commands/. These tools automatically run the audit against the /documentation/*.md set and embed findings into the shipping packet.

How the Skill Detects Code-Doc Gaps

The skill follows a rigorous five-step methodology defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md to surface discrepancies between intent and implementation.

Step 1: Establish Intent from Documentation

The skill first reads the documentation set that describes what the system should do. This includes permissions, data flows, and architectural constraints defined in markdown files. Without this documented intent—produced by the shipping-artifacts skill as defined in pm-ai-shipping/skills/shipping-artifacts/SKILL.md—the audit cannot proceed.

Step 2: Gather Implementation Evidence

Next, the skill scans source code for concrete enforcement points. It records the exact file and line number where each documented claim is implemented, such as decorators, middleware checks, or database query filters. Comments indicating intent, such as "internal only," are explicitly treated as insufficient evidence.

Step 3: Compare Claims to Code Execution Paths

For every documented rule, the skill verifies whether an enforcement point exists on every execution path. This step detects partial enforcement, where code validates a condition on some paths but not others, potentially exposing boundary crossings.

Step 4: Classify Security-Critical Mismatches

A mismatch only qualifies as a finding if it allows an actor to cross a trust, cost, data, or tenant boundary. Cosmetic drifts—where documentation and code differ but no security boundary is breached—are intentionally ignored to reduce noise.

Step 5: Produce Concrete Findings

Each validated finding contains the quoted intent, cited code evidence (or its absence), the attacker/victim scenario, and precise remediation guidance. If the skill cannot cite both the documentation and the corresponding code, it flags a question rather than a definitive finding.

Running the Audit in Practice

You can trigger the intended-vs-implemented audit through the ship-check command line interface.

Executing the Audit Locally

Run the following command from your project root:

pm-ai-shipping ship-check \
  --doc-dir ./documentation \
  --code-dir ./src \
  --skill intended-vs-implemented

The ship-check command, defined in pm-ai-shipping/commands/ship-check.md, walks the documentation and source files to produce a structured JSON report.

Understanding the JSON Output

The skill generates machine-readable findings that can be consumed by CI systems or security dashboards. Here is a sample report structure:

{
  "findings": [
    {
      "intent": "Only admins may delete a user (permissions.md)",
      "codeEvidence": "src/users/delete.py:27 – missing @admin_required decorator",
      "attacker": "Authenticated regular user",
      "victim": "Any user record",
      "remediation": "Add admin check or reject request early"
    },
    {
      "intent": "Cron jobs must run with restricted service account (cron.md)",
      "codeEvidence": "None – no job definition found",
      "attacker": "N/A (absence of control)",
      "victim": "System resources",
      "remediation": "Create cron job definition and enforce service‑account checks"
    }
  ]
}

Integrating with CI/CD Pipelines

Automate the audit in GitHub Actions to block merges when critical gaps exist:

# .github/workflows/audit.yml

steps:
  - name: Run Intended‑vs‑Implemented audit
    run: |
      pm-ai-shipping ship-check --doc-dir ./documentation --code-dir ./src --skill intended-vs-implemented > audit-report.json
  - name: Fail if critical gaps exist
    run: |
      jq '.findings | length > 0' audit-report.json && exit 1

Types of Code-Doc Gaps Detected

The skill categorizes discrepancies into three high-value patterns that generic linters cannot identify.

Undocumented-but-Enforced Code

When the codebase contains enforcement logic not reflected in documentation, the audit flags the documentation as stale. This ensures architectural docs remain accurate as the system evolves.

Documented-but-Unenforced Rules

This represents a direct security finding, such as a permission listed in permissions.md that lacks any enforcement point in the source code. These gaps expose the system to unauthorized access.

Partial Enforcement

The skill detects when validation exists on some execution paths but is missing on others. For example, an admin check might exist in the REST API layer but be absent in the internal service layer, allowing boundary crossing.

Summary

• The intended-vs-implemented skill compares documentation in architecture.md, permissions.md, and other specs against actual code enforcement in phuryn/pm-skills.
• It follows a five-step audit process defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md that requires documented intent before scanning for implementation evidence.
• The skill is invoked via ship-check, security-audit-static, and derive-tests commands located in /pm-ai-shipping/commands/.
• It detects three critical gap types: undocumented-but-enforced, documented-but-unenforced, and partial enforcement.
• Findings include exact file paths, line numbers, attacker/victim scenarios, and remediation steps, producing actionable JSON output for CI integration.

Frequently Asked Questions

What makes the intended-vs-implemented skill different from standard linters?

Standard linters verify internal code consistency, such as type safety or syntax rules, but lack a model of intent. The intended-vs-implemented skill requires documented intent first, then validates whether the code actually enforces those claims on every execution path, surfacing security boundaries that linters miss.

Can the skill run without documentation?

No. The skill depends on the shipping-artifacts skill to produce the documentation set. If the required markdown files in /documentation/*.md are missing or incomplete, the audit cannot establish intent and will flag questions rather than findings.

How does the skill handle false positives?

The skill ignores cosmetic differences and only reports mismatches that allow actors to cross trust, cost, data, or tenant boundaries. It also requires concrete code evidence—such as specific file paths and line numbers—before classifying a discrepancy as a finding, filtering out comment-based intent or undocumented assumptions.

Which commands trigger the intended-vs-implemented audit?

According to the phuryn/pm-skills source code, the skill is invoked by ship-check, security-audit-static, and derive-tests command scripts. These are defined in pm-ai-shipping/commands/ship-check.md, pm-ai-shipping/commands/security-audit-static.md, and related files within the repository.

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