tp-implementation-audit

name	tp-implementation-audit
description	Final audit of a completed plan — verify the full implementation against both design.md and detailed-design.md.
argument-hint	{design-name} [--auto] [--force-takeover]

Implementation Audit

Comprehensive review of a completed implementation against both design documents. This runs after all phases are done (unlike /tp-phase-review which reviews a single phase). It answers: "Did we build what we designed?"

Argument: {design-name} (required) — must match an existing directory under three-pillars-docs/tp-designs/.

Prerequisites

• three-pillars-docs/tp-designs/{design-name}/design.md must exist.
• three-pillars-docs/tp-designs/{design-name}/detailed-design.md must exist.
• three-pillars-docs/tp-designs/{design-name}/plan.md must exist with all phases marked as Done (or Skipped/Blocked).

Steps

0. Run first-run preflight per skills/_shared/first-run.md.

0. Preflight

Run the collaboration preflight per skills/_shared/collaboration.md with phase: "implementation-audit". This verifies the branch and refreshes the lock so the final audit artifact is written by the rightful owner. Honor --force-takeover if passed.

0b. Repo-map preamble (optional)

Per skills/_shared/repo-map-preamble.md. If aider is on PATH, generate a structural map of the codebase before walking design vs. implementation. Use it to focus interface-fidelity checks in Step 3 on files PageRank surfaces as load-bearing.

1. Load all design artifacts

Read design.md, detailed-design.md, plan.md, and any review.md files from the design directory. Do not skim — read fully. Also read project docs per skills/_shared/read-project-docs.md for project context.

2. Verify scope coverage against design.md

For EVERY item in design.md, verify it was implemented:

• Each "In scope" bullet → trace to implemented code. Is it done?
• Each entity → does it exist in the codebase with the described relationships?
• Each behavior → is it implemented and tested?
• Each constraint → is it respected? (performance, compatibility, resource limits)
• "Out of scope" items → verify nothing was accidentally implemented that shouldn't have been (scope creep).

3. Verify interface fidelity against detailed-design.md

For EVERY interface defined in detailed-design.md:

• Module structure → do files exist where the design said they would?
• Public APIs → do signatures match? Are input/output types correct?
• Data flow → does data move through the system as designed?
• Test strategy → are the specified test types (unit, integration, mocked boundaries) implemented as planned?

4. Run the full test suite

Run the project's complete test suite. Discover the test command from the project config (CLAUDE.md, Makefile, package.json, pyproject.toml, etc.):

{project-test-command} 2>&1 | tee "$(mktemp /tmp/test_output.XXXXXX.log)"

All tests must pass. Flag any failures.

5. Check for drift between phases

If multiple phases were implemented across separate sessions:

• Look for inconsistencies where later phases contradict earlier ones
• Check that shared interfaces still agree after all phases are done
• Verify no dead code was left from intermediate implementations that got refactored

6. Check for gaps

Things the design promised but the implementation may have missed:

• Edge cases mentioned in the design but not tested
• Error handling described in the design but not implemented
• Configuration or extension points described but not wired up
• Integration points described but not connected

7. Check for unintended additions

Things the implementation added that weren't in the design:

• Extra public APIs not in detailed-design.md
• Additional data structures or entities
• Behaviors beyond what design.md specified
• Flag these — they may be legitimate discoveries during implementation, but they should be acknowledged

8. Compile findings

Write three-pillars-docs/tp-designs/{design-name}/implementation-audit.md:

# <Design Name> — Implementation Audit

## Summary
<2-3 sentences: overall assessment, confidence that the design was faithfully implemented>

## Scope Coverage
| Design Item | Status | Notes |
|-------------|--------|-------|
| <item from design.md> | Done / Partial / Missing | {details} |

## Interface Fidelity
| Interface | Matches Design | Deviations |
|-----------|---------------|------------|
| <API/module from detailed-design.md> | Yes / Partial / No | <what differs> |

## Test Results
<test suite output summary — pass/fail counts>

## Gaps
- <things the design specified but the implementation missed>

## Unintended Additions
- <things implemented that weren't in the design — note if beneficial or accidental>

## Cross-Phase Drift
- <inconsistencies between phases, if any>

## Verdict
<One of: PASS — implementation faithfully matches design | PASS WITH NOTES — minor deviations documented above | NEEDS WORK — significant gaps listed above>

## Recommended Actions
- <concrete next steps if anything needs fixing>

9. Commit the artifact

Commit per skills/_shared/commit-after-work.md. Artifact paths to stage:

• three-pillars-docs/tp-designs/{design-name}/implementation-audit.md
• three-pillars-docs/tp-designs/{design-name}/lock.json (if refreshed)

Commit message: Audit: {design-name} implementation.

10. Present findings and prompt to invoke /tp-design-learn

Walk through the audit with the user. If the verdict is PASS, keep it brief. If NEEDS WORK, prioritize the gaps by severity and suggest whether to fix them, update the design to match reality, or accept the deviation.

After presenting the audit verdict, prompt the user to run /tp-design-learn immediately rather than relying on a soft reminder:

Run /tp-design-learn {design-name} now to keep project docs current? (yes / no — default yes)

• On yes (or empty response): invoke /tp-design-learn {design-name} via the Skill tool directly. The user doesn't have to context-switch; doc updates land in the same session while the audit's findings are fresh.
• On no: surface the existing required-next-step warning so the consequences are explicit:

  Required next step: Run /tp-design-learn {design-name} to propagate implementation results into product_roadmap.md, architecture.md, and known_issues.md, update the Design Inventory status, and scan for affected sibling designs. Do this BEFORE /tp-design-complete — that skill will refuse to archive a design whose roadmap status hasn't been updated (override available via --skip-learn for legacy designs only). Skipping this step causes the roadmap to go stale and downstream designs to miss critical updates.

This prompt is interactive-only. In --auto mode it does not fire — the autonomous chain is /tp-run-full-design Tier 5's responsibility, which already calls /tp-design-learn --auto after a clean audit verdict.

Rules

• Validate {design-name} per skills/_shared/validate-name.md.
• Respect the lock per skills/_shared/collaboration.md — the final audit should be written by the design's current owner. Pass --force-takeover to claim the design before auditing it.
• This is a final gate, not a phase-level review. Read EVERYTHING — both designs, the full plan, and all implemented code.
• The two design documents (design.md + detailed-design.md) are the source of truth. The implementation serves them.
• Deviations aren't automatically bad — implementations often discover things the design missed. But they must be acknowledged and documented.
• Don't re-review individual task quality (that's /tp-phase-review's job). Focus on the big picture: did we build what we set out to build?
• If existing review.md files from phase reviews flagged issues, check whether those issues were resolved.
• Keep implementation-audit.md under 80 lines. Dense and specific.

Auto Mode

--auto is Shape C verdict-only per skills/_shared/auto-mode.md — this skill produces an audit verdict in --auto, never edits code regardless of finding confidence. Steps 1–8 run unchanged (load artifacts, scope coverage, interface fidelity, test suite, drift, gap, addition checks, write implementation-audit.md). Step 10's interactive walk-through and the prompt-to-invoke-/tp-design-learn are both skipped — the autonomous chain is /tp-run-full-design Tier 5's responsibility, which already calls /tp-design-learn --auto after a clean audit verdict. This skill must NOT invoke /tp-design-learn from inside --auto mode: that would double-fire learn on the autonomous path and would re-introduce the "audit also writes docs" coupling that Shape C verdict-only explicitly forbids.

In --auto:

• Per-finding self-assessment. While compiling findings in step 8, self-assess Confidence: High | Medium | Low for each finding per the auto-mode convention. Confidence drives the verdict, not severity. Record confidence alongside the finding in the Gaps / Unintended Additions / Cross-Phase Drift sections of implementation-audit.md.
• Deterministic verdict rule. Compute the verdict from the confidence mix via "$TP_ROOT"/skills/_shared/auto_verdict.py::compute_verdict(confidences):
  • PASS — empty findings list. Exit 0.
  • PASS WITH NOTES — all findings are High confidence; no Medium or Low present. Exit 0.
  • NEEDS WORK — any Medium or Low finding present. Exit non-zero.
• Never auto-edit code or design artifacts. Even High-confidence findings are recorded as notes in implementation-audit.md; the human acts on them. This is the line between Shape C apply-fixes (/tp-design-audit) and Shape C verdict-only (this skill).
• Decisions log. Append a Decision Entry to three-pillars-docs/tp-designs/{design-name}/decisions.md with the verdict, finding count by confidence (e.g., 2 High, 0 Medium, 0 Low → PASS WITH NOTES), and Confidence: High (the verdict rule is deterministic, so the decision-to-emit-the-verdict is always high-confidence even when the underlying findings are not). Use [tp-implementation-audit] as the bare skill-name prefix.
• NEEDS WORK escalation. On NEEDS WORK, append a BLOCKED entry instead with Cause: medium-low-confidence-findings and Details: the full finding list with confidence labels, then exit non-zero so the orchestrator escalates.
• Use the canonical init/append snippet in skills/_shared/auto-mode.md to write decisions.md (create with schema-v1 header if missing, otherwise append).
• Lock conflict: handled by the collaboration preflight per the shared rule — exits BLOCKED with a decisions.md entry. Do not re-document here.
• Stage decisions.md alongside implementation-audit.md in step 9's commit.

Contract: in --auto, this skill writes a verdict and never edits code or design artifacts. The verdict-to-confidence-mix mapping is deterministic.