# How Intended-vs-Implemented Gap Analysis Works for Security Audits in phuryn/pm-skills

> Understand intended-vs-implemented gap analysis for security audits. Compare documented requirements against actual code to find vulnerabilities where system behavior diverges from design.

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

---

**The intended-vs-implemented gap analysis systematically compares documented security requirements against actual code enforcement to uncover critical vulnerabilities where system behavior diverges from design intent.**

The phuryn/pm-skills repository provides a specialized skill for conducting security audits that goes beyond traditional static analysis by introducing an *intent axis*. This method is particularly critical for AI-generated or rapidly evolving codebases, where the gap between what a system *should* do and what it *actually* does often represents the most dangerous attack surface.

## What Is Intended-vs-Implemented Gap Analysis?

Unlike traditional linters that only check internal code consistency, the **intended-vs-implemented** skill provides a systematic framework to identify security gaps arising from divergence between documented intent and implementation reality. The method treats Markdown documentation in `documentation/*.md` as the authoritative source of truth, then maps these requirements against concrete enforcement points in the production codebase.

## Architectural Overview of the Gap Analysis Method

The skill operates through a six-step boundary-focused process that examines trust, cost, data, and tenant crossings.

### Source of Truth: Documentation

All security-relevant intent is captured in Markdown files under `documentation/*.md` (specifically [`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 [`variables.md`](https://github.com/phuryn/pm-skills/blob/main/variables.md)). These files constitute the **intent model** for the audit, serving as the baseline against which all code is measured.

### Evidence Collection: Codebase Scan

The auditor scans production code to locate concrete enforcement points: authorization checks, query filters, input sanitizers, and access controls. Each finding records a precise citation to the exact file and line that implements—or fails to implement—the documented claim.

### Gap Comparison

For every documented rule, the analysis asks: *Does a matching enforcement point exist in code?* The comparison is performed **boundary-by-boundary**, focusing specifically on crossings involving trust boundaries, financial costs, sensitive data, or tenant isolation.

### Classification of Mismatches

Mismatches are categorized into two severity classes:

- **Matters**: The mismatch enables a real attacker to reach privileged data, finances, infrastructure, or another tenant's resources.
- **Doesn't Matter**: The disparity only affects the actor's own data or is purely cosmetic with no security impact.

### Finding Generation

Each security report includes four critical components:

1. **Documented intent** (quoted directly from the documentation file)
2. **Implemented reality** (precise code citation with file path and line number)
3. **Attacker and victim** scenario describing the exploitation path
4. **Concrete fix** (specific code change or documentation update)

If either the intent or implementation cannot be cited precisely, the issue is logged as an *investigation item* rather than a definitive finding.

### Integration with Larger Audits

The skill is invoked by the static security-audit command (`/security-audit-static`) and feeds results into broader security and performance audits. According to the source code 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), it complements traditional static analysis tools that focus on sink-level vulnerabilities rather than architectural intent.

> **Key Principle:** *Never fabricate intent.* If the documentation is silent on a rule, the audit notes the silence and recommends documenting the intent before proceeding.

## How to Trigger the Skill in phuryn/pm-skills

The intended-vs-implemented skill is integrated into two primary commands within the repository.

### Security Audit Static Command

The `/security-audit-static` command explicitly references the skill:

```markdown
Apply the **intended-vs-implemented** skill against `documentation/*.md`.

```

See the full command definition in [[`pm-ai-shipping/commands/security-audit-static.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md)](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md).

### Pre-Shipping Checks

The `ship-check` command also runs the skill to surface gaps before deployment:

```markdown
**Security** (`/security-audit-static`): apply the **intended-vs-implemented** skill ...

```

See the implementation in [[`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md)](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md).

## Practical Implementation Examples

### Running the Audit from the CLI

Execute the static security audit to invoke the gap analysis:

```bash

# Run the static security audit, which internally uses the intended-vs-implemented skill

pm-ai-shipping /security-audit-static

```

This generates a structured report listing each documented rule, corresponding code evidence (or lack thereof), and recommended remediation steps.

### Core Logic Implementation

The following Python pseudo-code illustrates the four-step method: *establish intent → gather evidence → compare → classify*:

```python
def intended_vs_implemented(doc_path, code_root):
    intents = parse_markdown_intents(doc_path)          # Step 1: Read intent docs

    evidence = collect_code_evidence(code_root)        # Step 2: Gather enforcement points

    findings = []
    for intent in intents:
        impl = evidence.get(intent.id)
        if not impl:
            findings.append({
                "type": "missing_implementation",
                "intent": intent.text,
                "recommendation": "Add enforcement in code"
            })
            continue

        if not matches(intent, impl):
            if is_critical(intent):
                findings.append({
                    "type": "critical_mismatch",
                    "intent": intent.text,
                    "code": impl.location,
                    "risk": "privilege_escalation",
                    "fix": "Align code with intent"
                })
    return findings

```

### Example Security Finding

Below is a representative YAML finding showing the complete audit output structure:

```yaml
- intent: "Only admins may delete user accounts"
  documented_in: "permissions.md:12"
  implemented_in: "src/users/delete_user.py:34"
  attacker: "Regular user"
  victim: "User data"
  severity: "high"
  fix: |
    # Add explicit admin check

    if not request.user.is_admin:
        raise PermissionError

```

## Key Files and Resources

The gap analysis functionality is distributed across these critical files in the phuryn/pm-skills repository:

- **[`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)**: Complete specification of the gap-analysis methodology
- **[`pm-ai-shipping/commands/security-audit-static.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md)**: CLI command definition that invokes the skill
- **[`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md)**: Pre-shipping command integrating the skill
- **[`pm-ai-shipping/README.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/README.md)**: Overview of the AI Shipping kit and skill purposes
- **[`README.md`](https://github.com/phuryn/pm-skills/blob/main/README.md)** (repo root): Lists the skill among core repository capabilities

## Summary

- **The intended-vs-implemented gap analysis** compares documented security requirements in `documentation/*.md` against actual code enforcement to identify architectural vulnerabilities.
- **The method uses six sequential steps**: documentation as source of truth, evidence collection, boundary-by-boundary comparison, severity classification, structured finding generation, and integration with broader audit workflows.
- **Classification distinguishes** between critical mismatches (enabling privilege escalation or data breaches) and cosmetic discrepancies with no security impact.
- **Key principle**: Never fabricate intent—if documentation is silent, the audit flags the gap for documentation rather than inventing requirements.
- **Integration points** include the `/security-audit-static` and `ship-check` commands, making the skill part of both dedicated security reviews and pre-deployment checks.

## Frequently Asked Questions

### What makes intended-vs-implemented analysis different from traditional static analysis?

Traditional static analysis tools focus on sink-level vulnerabilities like SQL injection or XSS by examining code patterns in isolation. The intended-vs-implemented method introduces an **intent axis** that validates whether security controls actually enforce documented business rules. While linters check if code is internally consistent, this skill verifies that code matches external requirements documented in `documentation/*.md`.

### How does the skill handle missing documentation?

According to the skill specification 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), the analysis follows a strict **"never fabricate intent"** principle. When the documentation is silent on a specific security rule, the audit does not assume requirements. Instead, it logs the absence as an investigation item and recommends documenting the intent before proceeding with implementation verification.

### Can the skill be used outside of the `/security-audit-static` command?

Yes. While primarily invoked through `/security-audit-static` as defined in [`pm-ai-shipping/commands/security-audit-static.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md), the skill is also integrated into the `ship-check` command (see [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md)). This dual integration ensures gap analysis runs both during dedicated security audits and as part of routine pre-shipping validations, preventing unintended deployments of privilege escalation vulnerabilities.

### What types of boundaries does the analysis focus on?

The comparison is performed **boundary-by-boundary**, specifically examining crossings involving four critical domains: **trust boundaries** (authentication/authorization), **cost boundaries** (financial operations), **data boundaries** (sensitive information access), and **tenant boundaries** (multi-tenant isolation). This boundary-focused approach ensures the classification of "Matters" vs "Doesn't Matter" prioritizes vulnerabilities with actual cross-boundary impact.