# How the Intended-vs-Implemented Skill Detects Documentation-Code Gaps

> Discover how the Intended-vs-Implemented skill systematically audits security boundaries, bridging documentation and code gaps with a five-step verification workflow. Improve your security posture.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: deep-dive
- Published: 2026-06-23

---

**The Intended-vs-Implemented skill is a systematic audit method that bridges the gap between documented security boundaries and actual code enforcement through a rigorous five-step verification workflow.**

The `intended-vs-implemented` skill, located in the `phuryn/pm-skills` repository, provides a structured methodology for identifying when implementation diverges from documentation. This skill treats markdown files such as [`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) as the canonical source of truth, then validates every documented claim against concrete enforcement points in the codebase.

## The Five-Step Documentation-to-Code Audit Workflow

The core audit methodology is defined 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 operates through a systematic comparison process that ensures no documented rule goes unverified.

### 1. Establish Intent from Documentation

The skill begins by ingesting the repository’s documentation artifacts. These markdown files serve as the **source of truth** for expected security or functional boundaries ([line 20-21](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md#L20)). 

Common documentation targets include:
- [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md) – Access control rules and privilege requirements
- [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md) – System boundaries and component responsibilities  
- [`variables.md`](https://github.com/phuryn/pm-skills/blob/main/variables.md) – Environment constraints and configuration limits

### 2. Gather Concrete Implementation Evidence

For each documented claim, the skill scans the codebase to extract **enforcement points**—the exact files and line numbers where checks, filters, or sanitizers occur. A valid citation must be a real code reference, not a vague comment or implicit assumption ([line 22-23](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md#L22)).

### 3. Compare Claims to Code Execution Paths

The skill iterates over each documented rule and verifies whether an enforcement point actually implements the rule on **every relevant execution path**. It treats ambiguous comments such as "handled elsewhere" as insufficient until a concrete code path is verified ([line 24-25](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md#L24)).

### 4. Classify Trust-Boundary Mismatches

A gap is considered **meaningful** only when the discrepancy crosses a trust, cost, data, or tenant boundary. Cosmetic drift—such as typos in comments—is filtered out, while missing permission checks that could expose private data are flagged as high-priority findings ([line 26-27](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md#L26)).

### 5. Document Actionable Findings

Each validated finding must contain four components: the exact documented intent, the concrete implementation evidence (or explicit lack thereof), the attacker/victim scenario, and a concrete remediation step. If either side of the gap cannot be cited with line-specific references, the issue is marked as **"needs investigation"** rather than a definitive finding ([line 28-29](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md#L28)).

## Defining Intent vs. Implementation Evidence

The skill establishes strict definitions for what constitutes valid **intent** and **implementation evidence** ([line 30-34](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md#L30)).

- **Intent** must be explicit in documentation, not inferred from code behavior
- **Implementation evidence** must be a specific code construct (permission check, input validation, etc.) with file path and line number
- Implicit enforcement through side effects is rejected as insufficient evidence

## Running the Skill via CLI

The `pm-ai-shipping` plugin suite exposes this skill through a generic CLI. The skill consumes documentation bundles and performs the gap analysis against source directories.

### Standalone Audit

Run the audit against a specific permissions document:

```bash
pm audit intended-vs-implemented \
   --docs ./docs/permissions.md \
   --src ./src

```

**Expected output structure:**

```text
── Gap Detected ─────────────────────────────────────
Documented Intent: "Only admins may delete a user" (permissions.md:12)
Implementation Evidence: src/users/delete.js:8 – missing admin check
Impact: Any authenticated user can delete arbitrary accounts
Recommendation: Add admin-only guard to delete endpoint

```

### Integrated Workflow with Shipping Artifacts

The skill integrates with the `shipping-artifacts` skill to process documentation artifacts before analysis:

```bash

# First, gather documentation artefacts

pm run shipping-artifacts \
   --output ./documentation

# Then run the gap analysis

pm run intended-vs-implemented \
   --docs ./documentation \
   --src ./src \
   --report ./audit-report.md

```

This workflow is orchestrated in [`pm-ai-shipping/commands/ship-check.md`](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/commands/ship-check.md), which coordinates the full audit pipeline.

## Handling Edge Cases

The skill provides specific guidance for two common scenarios ([line 38-40](https://github.com/phuryn/pm-skills/blob/main/pm-ai-shipping/skills/intended-vs-implemented/SKILL.md#L38)):

- **Undocumented-but-enforced**: Code implements a restriction not mentioned in documentation. The skill flags this as "implicit intent" requiring documentation updates.
- **Documented-but-unenforced**: Documentation claims a restriction exists, but no code enforces it. This is flagged as a critical security gap requiring immediate remediation.

## Summary

- The **Intended-vs-Implemented** skill audits repositories by comparing documentation against concrete code enforcement points.
- It requires **line-specific citations** for both intent (from docs) and implementation (from code), rejecting vague references.
- Only mismatches crossing **trust, cost, data, or tenant boundaries** are reported as meaningful findings.
- The skill integrates with the `shipping-artifacts` skill to process documentation bundles before analysis.
- Findings include attacker scenarios and concrete remediation steps, or are flagged as "needs investigation" when evidence is incomplete.

## Frequently Asked Questions

### What makes a documentation-code gap "meaningful" versus cosmetic?

A gap is classified as meaningful only when it crosses a **trust boundary**, **cost boundary**, **data boundary**, or **tenant boundary**. For example, a missing permission check that allows unauthorized data access is meaningful, while a typo in a comment describing a valid check is considered cosmetic drift and ignored.

### How does the skill handle enforcement that exists in code but not in documentation?

When code implements restrictions not documented in [`permissions.md`](https://github.com/phuryn/pm-skills/blob/main/permissions.md) or [`architecture.md`](https://github.com/phuryn/pm-skills/blob/main/architecture.md), the skill flags these as **undocumented-but-enforced** cases. These are treated as "implicit intent" requiring documentation updates to ensure the security model is explicit and maintainable.

### What constitutes valid implementation evidence for a documented claim?

Valid implementation evidence must be a **concrete enforcement point**—a specific file and line number containing a permission check, input validator, or sanitizer. Vague comments, implicit behavior, or references to "handled elsewhere" are rejected as insufficient until a concrete code path is verified.

### Can the Intended-vs-Implemented skill run independently of other pm-skills tools?

Yes, the skill can run standalone using `pm audit intended-vs-implemented` with direct `--docs` and `--src` parameters. However, it is designed to work optimally with the `shipping-artifacts` skill, which standardizes documentation extraction before the audit begins.