Using the PM Skills Intended-vs-Implemented Gap Analysis Skill: A Complete Guide

The intended-vs-implemented gap analysis skill helps product managers and security reviewers surface critical security bugs by comparing documented system requirements against actual code enforcement points, reporting only gaps that cross trust, cost, data, or tenant boundaries.

The intended-vs-implemented gap analysis skill is a core component of the pm-ai-shipping kit in the phuryn/pm-skills repository. This skill bridges the dangerous gap between documentation and implementation, ensuring that what the system should do according to specification matches what it actually does in code.

The Four-Step Gap Analysis Method

The skill follows a rigorous four-step method documented 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 step builds a complete picture of where intent diverges from reality.

Establish Intent

The skill first consumes the set of Markdown files under the documentation/ directory (e.g., permissions.md, architecture.md). These files serve as the single source of truth for what the system should do. The methodology requires that intent be documented explicitly before comparison can begin.

Gather Implementation Evidence

Next, the skill scans the codebase for concrete enforcement points such as authorization checks, query filters, and input sanitizers. Unlike generic static analysis tools, this method requires file-and-line citations—vague comments like "validated elsewhere" do not qualify as evidence.

Compare Claim to Code

For each documented rule, the skill verifies that an enforcement point exists on every execution path. If a specific permission check is documented but missing from even one code path, the comparison flags a mismatch. This step catches the most dangerous class of bugs: assumed but unenforced security boundaries.

Classify Mismatches

Not every discrepancy gets reported. The skill filters findings through a strict classification system, reporting only gaps that cross a trust, cost, data, or tenant boundary. Cosmetic drift—such as renamed variables or refactoring artifacts—is intentionally ignored to focus security reviews on exploitable vulnerabilities.

How to Run the Intended-vs-Implemented Skill

You can invoke the gap analysis through the command line interface or programmatically via the Python API.

Command Line Invocation

Run the skill directly inside any repository that has the pm-ai-shipping plugin enabled:

/pm-ai-shipping:intended-vs-implemented

This command reads the documentation files from documentation/, walks the source tree for enforcement points, and prints a JSON report containing any discovered gaps.

Programmatic Usage with the Auditor Class

For CI pipeline integration, import the Auditor class from pm-ai-shipping/__init__.py. This class encapsulates the four-step method described in the skill documentation.

from pm_ai_shipping.intended_vs_implemented import Auditor
import pathlib

repo_root = pathlib.Path('.')
auditor = Auditor(repo_root)

# Load documentation (all *.md under documentation/)

docs = auditor.load_intent_docs()

# Scan source files for enforcement points

evidence = auditor.collect_implementation_evidence()

# Produce the gap report

report = auditor.compare(docs, evidence)

for finding in report.findings:
    print(f"❗ {finding.intent}")
    print(f"   → {finding.implementation}")
    print(f"   Impact: {finding.attacker} → {finding.victim}")
    print(f"   Fix: {finding.remediation}\n")

The Auditor class ensures your automation stays synchronized with the official methodology defined in SKILL.md.

Understanding the Output Format

Every finding produced by the intended-vs-implemented skill contains five required fields that make the report actionable for security reviewers:

• Documented intent: The exact quote from the documentation file
• Implemented reality: Precise file and line citation (e.g., src/user/routes.py:124)
• Attacker persona: Who can exploit this gap
• Victim persona: Who suffers from the exploit
• Concrete fix: Specific remediation steps

Example output structure:

{
  "findings": [
    {
      "intent": "Only admins may delete a user",
      "implementation": "src/user/routes.py:124",
      "attacker": "authenticated non‑admin",
      "victim": "any user record",
      "remediation": "Add admin‑only guard to delete endpoint"
    }
  ]
}

Integration with the Full Ship-Check Workflow

The intended-vs-implemented skill works as part of a comprehensive audit pipeline. The top-level command ship-check (documented in pm-ai-shipping/commands/ship-check.md) orchestrates the complete workflow:

/pm-ai-shipping:ship-check

This executes the following sequence automatically:

1. document-app: Creates the documentation set under documentation/
2. intended-vs-implemented: Performs the gap analysis against the code
3. security-audit-static: Cross-references findings with trust-boundary mapping
4. performance-audit-static: Adds performance-related gaps to the report
5. derive-tests: Maps existing test coverage against documented intent

The complete results compile into a reviewer-ready packet that bridges the "intent" axis missing from generic linters and static analysis tools.

Summary

• The intended-vs-implemented gap analysis skill uses a four-step method: establish intent, gather evidence, compare claims to code, and classify mismatches across trust boundaries.
• Invoke the skill via /pm-ai-shipping:intended-vs-implemented or programmatically using the Auditor class from pm-ai_shipping/intended_vs_implemented.
• Findings always include documented intent, file-and-line citations, attacker/victim personas, and concrete fixes.
• The skill integrates into the broader ship-check workflow alongside static security and performance audits.
• Only gaps crossing trust, cost, data, or tenant boundaries are reported; cosmetic code drift is filtered out.

Frequently Asked Questions

What types of gaps does the intended-vs-implemented skill ignore?

The skill filters out cosmetic drift such as variable renaming, formatting changes, or refactoring artifacts that do not affect security boundaries. According to the classification rules in SKILL.md, only mismatches that cross trust, cost, data, or tenant boundaries generate findings. This prevents noise in security reviews while surfacing exploitable vulnerabilities.

How does the Auditor class load documentation files?

The Auditor.load_intent_docs() method scans the documentation/ directory for all *.md files, treating them as the single source of truth for system intent. These files typically include permissions.md, architecture.md, and other Markdown documents that specify what the system should enforce. The method parses these into a structured format for comparison against implementation evidence.

Can I run this skill without the full ship-check workflow?

Yes. While the ship-check command orchestrates a complete audit pipeline, you can run the intended-vs-implemented analysis independently using either the /pm-ai-shipping:intended-vs-implemented command or the Auditor class directly. This modular approach allows teams to integrate gap analysis into existing CI/CD pipelines without triggering the document generation or test derivation steps.

What makes a finding "actionable" in the gap analysis report?

A finding becomes actionable when it contains all five required fields: the exact documented intent (quoted from documentation/), the implemented reality (specific file and line number), the attacker and victim personas, and a concrete fix. Findings missing enforcement points on any execution path automatically include these details, allowing security teams to prioritize fixes based on actual exploitability rather than theoretical risk.

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