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

The intended-vs-implemented skill performs a systematic audit that compares documented intent against actual code enforcement to expose security and correctness gaps that traditional linters cannot detect.

The phuryn/pm-skills repository provides a framework for AI-assisted product management shipping workflows, with the intended-vs-implemented skill serving as a critical security and correctness audit mechanism. Unlike generic static analysis tools that only verify internal code consistency, this skill validates whether the system actually enforces what its documentation promises. By cross-referencing files like architecture.md and permissions.md against concrete enforcement points in the source code, it surfaces high-risk mismatches before they reach production.

The Five-Step Audit Process

The skill executes a disciplined comparison defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md. It treats documentation as a specification and code as evidence, rejecting superficial matches such as code comments that merely mention intent.

1. Establish Intent from Documentation

The skill first ingests the documentation set—typically including architecture.md, flows.md, and permissions.md—to extract explicit claims about system behavior. These files describe what the system should do, establishing the ground truth for the audit. The companion shipping-artifacts skill generates this documentation set according to pm-ai-shipping/skills/shipping-artifacts/SKILL.md.

2. Gather Implementation Evidence

Next, the skill scans the source code for concrete enforcement points. It searches for authorization checks, query filters, input sanitizers, and other boundary controls, recording the exact file path and line number where each rule is implemented. This step creates a traceable map between documented claims and their supposed enforcement locations.

3. Compare Claims to Code Enforcement

For every documented rule, the skill verifies whether an enforcement point exists on every execution path. It treats comments such as "internal only" as insufficient evidence—only active code constructs like decorators, middleware, or explicit checks qualify. This comparison identifies whether the implementation fully covers the documented intent or leaves gaps.

4. Classify Security-Critical Mismatches

Not every drift between docs and code constitutes a finding. The skill applies a severity filter: a mismatch matters only when it allows an actor to cross a trust, cost, data, or tenant boundary. Cosmetic discrepancies or internal refactoring differences are ignored, while missing authorization checks or exposed public fields are flagged as critical vulnerabilities.

5. Produce Concrete Findings

Each validated finding contains four components: the quoted intent from documentation, the cited code evidence (or explicit absence), the attacker and victim scenario, and a precise remediation step. If the skill cannot cite both the documentation claim and the corresponding code location, it generates a question rather than a definitive finding, prompting human review.

Critical Gap Types Detected

The intended-vs-implemented skill surfaces three specific categories of high-value bugs that generic linters miss:

• Undocumented-but-enforced code: The implementation contains security checks that never appear in documentation, indicating stale or incomplete docs. The audit flags these for documentation updates to prevent future maintenance errors.

• Documented-but-unenforced rules: A permission listed in permissions.md lacks a corresponding enforcement point in the code. This represents a direct security vulnerability where documented access controls are illusory.

• Partial enforcement: Code enforces a rule on some execution paths but not others, creating inconsistent boundary protection that attackers can exploit through edge-case requests.

Running the Audit: Practical Examples

The skill integrates into CI/CD pipelines through command scripts located in /pm-ai-shipping/commands/*.md, including ship-check, security-audit-static, and derive-tests.

Command-Line Execution

Invoke the audit using the ship-check command:

# In a CI step or local dev session

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

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

Sample JSON Output

The skill produces machine-readable findings suitable for automated gates:

{
  "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"
    }
  ]
}

CI/CD Integration

Block merges when critical gaps exist by integrating the audit into GitHub Actions:

# .github/workflows/audit.yml

steps:
  - name: Run Intended‑vs‑Implemented audit
    run: |
      pm-ai-shipping ship-check ... > audit-report.json
  - name: Fail if critical gaps exist
    run: |
      jq '.findings | length > 0' audit-report.json && exit 1

This configuration ensures that documented-but-unenforced rules prevent deployment.

Key Source Files and Architecture

The skill's logic and integration points are defined across several files in the phuryn/pm-skills repository:

File	Role
pm-ai-shipping/skills/intended-vs-implemented/SKILL.md	Full specification of the audit method and comparison logic.
pm-ai-shipping/skills/shipping-artifacts/SKILL.md	Defines the documentation set that supplies intent for the audit.
pm-ai-shipping/commands/ship-check.md	CLI entry point that runs the skill as part of shipping checklists.
pm-ai-shipping/commands/security-audit-static.md	Demonstrates applying the skill during static security reviews.
pm-ai-shipping/README.md	High-level overview of the AI Shipping Kit including this skill.

Summary

• The intended-vs-implemented skill in phuryn/pm-skills bridges the gap between documentation and code by systematically comparing documented intent against actual enforcement points.
• It executes a five-step audit process defined in SKILL.md, rejecting superficial evidence like comments in favor of concrete code constructs.
• The skill specifically targets security-critical mismatches involving trust, cost, data, or tenant boundaries, ignoring cosmetic drifts.
• It detects three high-risk patterns: undocumented enforcement, missing enforcement for documented rules, and partial path coverage.
• Integration occurs through commands like ship-check, producing structured JSON reports that can gate CI/CD pipelines.

Frequently Asked Questions

What makes the intended-vs-implemented skill different from static analysis tools?

Traditional static analysis tools verify internal code consistency such as type safety or lint rules, but they lack a model of intent. The intended-vs-implemented skill requires documented specifications first—generated by the shipping-artifacts skill—and validates whether the code actually enforces those specifications. This allows it to catch logical security gaps that syntactic analysis cannot detect.

Can the skill run without existing documentation?

No, the audit requires a documentation set as input. The skill is designed to work alongside the shipping-artifacts skill, which produces the architecture.md, permissions.md, and other specification files. If documentation is missing or incomplete, the skill will flag questions rather than findings, prompting the team to update the docs before proceeding.

How does the skill distinguish between critical and cosmetic mismatches?

The skill applies a boundary-based severity filter defined in pm-ai-shipping/skills/intended-vs-implemented/SKILL.md. A mismatch only generates a finding if it could allow an actor to cross a trust, cost, data, or tenant boundary. Comments that disagree with implementation details, or refactorings that don't affect security postures, are ignored to reduce noise.

What happens when the skill cannot find evidence for a documented rule?

When the skill locates a documented claim but cannot find corresponding enforcement code—or vice versa—it produces a structured finding with "codeEvidence": "None" or flags a question for human review. This ensures that the audit never assumes missing evidence implies malicious intent, instead requiring explicit verification of both the documentation and implementation sides.

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