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

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, architecture.md, and 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, 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:

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).

Pre-Shipping Checks

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

**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).

Practical Implementation Examples

Running the Audit from the CLI

Execute the static security audit to invoke the gap analysis:

# 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:

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:

- 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: Complete specification of the gap-analysis methodology
• pm-ai-shipping/commands/security-audit-static.md: CLI command definition that invokes the skill
• pm-ai-shipping/commands/ship-check.md: Pre-shipping command integrating the skill
• pm-ai-shipping/README.md: Overview of the AI Shipping kit and skill purposes
• 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, 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, the skill is also integrated into the ship-check command (see 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.

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