# Methodology Behind the Intended-vs-Implemented Audit Skill: A 5-Step Security Framework

> Learn the 5-step methodology behind the intended-vs-implemented audit skill. Discover how this security framework ensures actual code enforcement aligns with documented boundaries for actionable findings.

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

---

**The intended-vs-implemented audit skill applies a rigorous five-step methodology to compare documented system boundaries against actual code enforcement, producing actionable security findings only when discrepancies cross trust, cost, data, or tenant boundaries.**

The **intended-vs-implemented** skill in the `phuryn/pm-skills` repository provides a systematic framework for auditing gaps between documented security requirements and their implementation in source code. Unlike generic code reviews, this methodology treats documentation as untrusted input that must be verified against concrete enforcement points, ensuring that every reported finding includes specific file references, attacker scenarios, and remediation steps.

## The 5-Step Audit Methodology

According to the skill definition 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 audit proceeds through five discrete phases:

### 1. Establish Documented Intent

The audit begins by reading the markdown documentation set—typically files like [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md) and [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md) within a `documentation/` directory—to establish the **source of truth** for intended security and functional boundaries. These documents define the rules, scopes, and classifications that the system is supposed to enforce, such as "admin-only endpoint" or "tenant-isolated data."

### 2. Gather Implementation Evidence

The methodology requires locating the concrete **enforcement points** in the codebase that correspond to each documented rule. This includes authorization checks, query filters, and input sanitizers. Crucially, evidence must be cited as precise file and line references—vague comments or assumptions are insufficient. As implemented in `phuryn/pm-skills`, this step demands provable presence or absence of enforcement mechanisms.

### 3. Compare Claims to Evidence

For every documented rule, the audit verifies whether an enforcement point exists on **every execution path**. The comparison happens one boundary at a time, checking that the documented intent aligns with the implemented reality. Inconsistent or missing checks are flagged as potential mismatches for further classification.

### 4. Classify Mismatches by Security Impact

Not every discrepancy warrants a finding. The methodology classifies mismatches based on whether they allow an unauthorized actor to reach sensitive data, financial resources, infrastructure, or another tenant’s environment. **Cosmetic drifts**—where documentation and code differ but no security boundary is crossed—are explicitly ignored.

### 5. Avoid Hand-Wavy Findings

Every reported gap must include four specific elements: the exact documented intent, the exact code location, the attacker/victim scenario, and a concrete fix. If any of these elements cannot be cited with precision, the item is treated as an open investigation rather than a definitive finding. This prevents the generation of unactionable audit noise.

## Defining Intent, Evidence, and Meaningful Mismatches

The methodology establishes strict definitions for three critical concepts:

- **Intent** — A documented rule, boundary, scope, or classification (e.g., "admin-only endpoint") sourced from the `documentation/*.md` files.

- **Implementation Evidence** — A cited enforcement point in the source code (or provable absence thereof), referenced by specific file path and line number.

- **Meaningful Mismatch** — A discrepancy between documented rules and code that **crosses a trust, cost, data, or tenant boundary**. Only these qualify as security findings; cosmetic inconsistencies are filtered out.

## Running the Audit: Practical Examples

The skill integrates into the shipping workflow through specific commands and can be invoked manually for custom CI pipelines.

### Running the Static Security Audit

To execute the intended-vs-implemented audit as part of a security review:

```bash

# From the repository root, trigger the static security audit

# which internally applies the intended-vs-implemented skill

$ /security-audit-static

```

This command initiates the five-step audit process described in the shipping sequence, analyzing documentation against the source tree.

### Full Shipping Check Integration

For a comprehensive review that includes the audit alongside performance and coverage checks:

```bash

# Generate a complete shipping packet including the audit

$ /ship-check

```

The `/ship-check` command orchestrates the full audit sequence, combining documentation validation, security auditing using this skill, and test-coverage mapping as defined in [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md).

### Programmatic Usage in Custom Scripts

Developers can embed the logic directly into Python-based CI pipelines:

```python

# Re-use the skill logic in custom automation

from pm_ai_shipping.skills.intended_vs_implemented import audit_intent_vs_code

docs = load_markdown_folder('documentation/')    # Intent sources

code = load_source_tree('src/')                  # Implementation evidence

findings = audit_intent_vs_code(docs, code)

for finding in findings:
    print(f"Intent: {finding.intent}")
    print(f"Location: {finding.code_location}")
    print(f"Risk: {finding.risk}, Fix: {finding.fix}")

```

The `audit_intent_vs_code` function encapsulates the complete methodology, returning structured findings that include the risk classification and concrete remediation steps.

## Key Source Files and Implementation

The methodology is implemented across several 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)** — Contains the core five-step methodology, definitions of intent/evidence/mismatch, and guidelines for classifying findings.

- **[`pm-ai-shipping/commands/security-audit-static.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/security-audit-static.md)** — Orchestrates the skill during static security reviews, triggering the comparison between documentation and code.

- **[`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md)** — Runs the full audit sequence including the intended-vs-implemented check as part of the shipping workflow.

- **[`pm-ai-shipping/skills/shipping-artifacts/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/shipping-artifacts/SKILL.md)** — Produces the documentation artifacts that serve as the *intent* source for the audit.

## Summary

- The intended-vs-implemented skill uses a **five-step methodology**: establish intent, gather evidence, compare claims, classify mismatches, and require concrete citations.

- **Documented-but-unenforced** rules are always reported as findings ranked by risk, while **undocumented-but-enforced** rules are flagged as documentation staleness, not security issues.

- Only mismatches that **cross trust, cost, data, or tenant boundaries** qualify as meaningful security findings; cosmetic drifts are ignored.

- Every finding must cite the exact documentation, exact code location, attacker scenario, and concrete fix—otherwise it remains an open investigation.

- The methodology treats both documentation and code as **untrusted inputs**, never fabricating intent when documentation is missing.

## Frequently Asked Questions

### What is the difference between documented-but-unenforced and undocumented-but-enforced rules?

**Documented-but-unenforced** rules occur when the documentation specifies a security boundary (such as "only admins can access this endpoint") but the code lacks the corresponding enforcement check—these are always reported as security findings. **Undocumented-but-enforced** rules occur when the code implements a restriction that isn't mentioned in the documentation—these are flagged as stale or incomplete documentation rather than security vulnerabilities, since the system is actually protected.

### How does the audit handle missing documentation?

If no documentation exists for a particular component, the methodology explicitly **refuses to fabricate intent**. Instead of assuming what the system should do, the audit reports that the documentation is missing. This prevents the introduction of false assumptions about security requirements and forces teams to formally document boundaries before they can be verified.

### What makes a mismatch "meaningful" versus cosmetic?

A mismatch is considered **meaningful** only when the gap between documentation and implementation allows an unauthorized actor to access sensitive data, incur costs, touch infrastructure, or cross into another tenant's environment. If the discrepancy involves internal refactoring, naming conventions, or architectural patterns that do not affect security boundaries, it is classified as cosmetic and excluded from findings.

### Can the intended-vs-implemented skill be used outside of security audits?

Yes. While the methodology feeds into **security** and **performance** audits, the underlying `audit_intent_vs_code` function can be imported and used in any CI pipeline or custom script to verify that functional requirements documented in markdown files match the actual code implementation. It does not replace lower-level static analysis but serves as a high-level consistency check between specification and reality.