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

> Master the intended-vs-implemented gap analysis skill to uncover critical security bugs. Compare requirements to code and find gaps crossing trust, cost, data, or tenant boundaries. Learn how in this complete guide.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: how-to-guide
- Published: 2026-07-05

---

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

```bash
/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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/__init__.py). This class encapsulates the four-step method described in the skill documentation.

```python
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`](https://github.com/phuryn/pm-skills/blob/main/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:

```json
{
  "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`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md)) orchestrates the complete workflow:

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