How the Intended-vs-Implemented Skill Detects Documentation-Code Gaps

The Intended-vs-Implemented skill is a systematic audit method that bridges the gap between documented security boundaries and actual code enforcement through a rigorous five-step verification workflow.

The intended-vs-implemented skill, located in the phuryn/pm-skills repository, provides a structured methodology for identifying when implementation diverges from documentation. This skill treats markdown files such as permissions.md, architecture.md, and variables.md as the canonical source of truth, then validates every documented claim against concrete enforcement points in the codebase.

The Five-Step Documentation-to-Code Audit Workflow

The core audit methodology is defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md. It operates through a systematic comparison process that ensures no documented rule goes unverified.

1. Establish Intent from Documentation

The skill begins by ingesting the repository’s documentation artifacts. These markdown files serve as the source of truth for expected security or functional boundaries (line 20-21).

Common documentation targets include:

• permissions.md – Access control rules and privilege requirements
• architecture.md – System boundaries and component responsibilities
• variables.md – Environment constraints and configuration limits

2. Gather Concrete Implementation Evidence

For each documented claim, the skill scans the codebase to extract enforcement points—the exact files and line numbers where checks, filters, or sanitizers occur. A valid citation must be a real code reference, not a vague comment or implicit assumption (line 22-23).

3. Compare Claims to Code Execution Paths

The skill iterates over each documented rule and verifies whether an enforcement point actually implements the rule on every relevant execution path. It treats ambiguous comments such as "handled elsewhere" as insufficient until a concrete code path is verified (line 24-25).

4. Classify Trust-Boundary Mismatches

A gap is considered meaningful only when the discrepancy crosses a trust, cost, data, or tenant boundary. Cosmetic drift—such as typos in comments—is filtered out, while missing permission checks that could expose private data are flagged as high-priority findings (line 26-27).

5. Document Actionable Findings

Each validated finding must contain four components: the exact documented intent, the concrete implementation evidence (or explicit lack thereof), the attacker/victim scenario, and a concrete remediation step. If either side of the gap cannot be cited with line-specific references, the issue is marked as "needs investigation" rather than a definitive finding (line 28-29).

Defining Intent vs. Implementation Evidence

The skill establishes strict definitions for what constitutes valid intent and implementation evidence (line 30-34).

• Intent must be explicit in documentation, not inferred from code behavior
• Implementation evidence must be a specific code construct (permission check, input validation, etc.) with file path and line number
• Implicit enforcement through side effects is rejected as insufficient evidence

Running the Skill via CLI

The pm-ai-shipping plugin suite exposes this skill through a generic CLI. The skill consumes documentation bundles and performs the gap analysis against source directories.

Standalone Audit

Run the audit against a specific permissions document:

pm audit intended-vs-implemented \
   --docs ./docs/permissions.md \
   --src ./src

Expected output structure:

── Gap Detected ─────────────────────────────────────
Documented Intent: "Only admins may delete a user" (permissions.md:12)
Implementation Evidence: src/users/delete.js:8 – missing admin check
Impact: Any authenticated user can delete arbitrary accounts
Recommendation: Add admin-only guard to delete endpoint

Integrated Workflow with Shipping Artifacts

The skill integrates with the shipping-artifacts skill to process documentation artifacts before analysis:

# First, gather documentation artefacts

pm run shipping-artifacts \
   --output ./documentation

# Then run the gap analysis

pm run intended-vs-implemented \
   --docs ./documentation \
   --src ./src \
   --report ./audit-report.md

This workflow is orchestrated in pm-ai-shipping/commands/ship-check.md, which coordinates the full audit pipeline.

Handling Edge Cases

The skill provides specific guidance for two common scenarios (line 38-40):

• Undocumented-but-enforced: Code implements a restriction not mentioned in documentation. The skill flags this as "implicit intent" requiring documentation updates.
• Documented-but-unenforced: Documentation claims a restriction exists, but no code enforces it. This is flagged as a critical security gap requiring immediate remediation.

Summary

• The Intended-vs-Implemented skill audits repositories by comparing documentation against concrete code enforcement points.
• It requires line-specific citations for both intent (from docs) and implementation (from code), rejecting vague references.
• Only mismatches crossing trust, cost, data, or tenant boundaries are reported as meaningful findings.
• The skill integrates with the shipping-artifacts skill to process documentation bundles before analysis.
• Findings include attacker scenarios and concrete remediation steps, or are flagged as "needs investigation" when evidence is incomplete.

Frequently Asked Questions

What makes a documentation-code gap "meaningful" versus cosmetic?

A gap is classified as meaningful only when it crosses a trust boundary, cost boundary, data boundary, or tenant boundary. For example, a missing permission check that allows unauthorized data access is meaningful, while a typo in a comment describing a valid check is considered cosmetic drift and ignored.

How does the skill handle enforcement that exists in code but not in documentation?

When code implements restrictions not documented in permissions.md or architecture.md, the skill flags these as undocumented-but-enforced cases. These are treated as "implicit intent" requiring documentation updates to ensure the security model is explicit and maintainable.

What constitutes valid implementation evidence for a documented claim?

Valid implementation evidence must be a concrete enforcement point—a specific file and line number containing a permission check, input validator, or sanitizer. Vague comments, implicit behavior, or references to "handled elsewhere" are rejected as insufficient until a concrete code path is verified.

Can the Intended-vs-Implemented skill run independently of other pm-skills tools?

Yes, the skill can run standalone using pm audit intended-vs-implemented with direct --docs and --src parameters. However, it is designed to work optimally with the shipping-artifacts skill, which standardizes documentation extraction before the audit begins.

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