pm-audit

PM - Audit (Workspace Health Check)

Agent mode (--agent)

Supports --agent: runs autonomously in a subagent, drafts the artifact from existing inputs, and returns a short summary + coverage note.

• No flag → interactive (default); if inputs are heavy, offer agent mode.
• --agent → obey. First check inputs are complete. Anything missing: do NOT invent it - mark [ASSUMED - what/why] in the output and summary. Never hallucinate to fill a gap.

What this skill does

Scans an existing Pureinn workspace and reports - then fixes - where its own artifacts drifted from the current framework conventions. It is the productized version of a manual consistency pass: ID and naming integrity, cross-reference resolution, structural conformance, lifecycle validity, completeness, and framework-version drift (artifacts from an older Pureinn version that miss newer fields or use old names).

Two tiers, two different jobs:

• Tier 1 - Form. Naming, IDs, cross-refs, lifecycle, schema, metadata parity. Mechanical - auto-fixed in place. This is the classic audit.
• Tier 2 - Strategic consistency (substance). Does the strategic layer still agree with itself and with the research it was built on - PRD Target Customer vs. personas, value prop vs. research pains, roadmap phases vs. feature phases, pricing vs. WTP? This tier is read-only: it never auto-edits strategic content (that is a business decision). It surfaces each contradiction as [CONFLICT] and routes the fix to the authoring skill (pm-prd, pm-product-roadmap, pm-business-model, ...), which re-runs in delta mode. Run Tier 2 after a research injection or strategic pivot, and before a build commitment or pitch.

Run it when:

• A workspace was built with an older Pureinn version and you want it brought current
• Right after pm-reconcile or pm-reverse-extract, as a verification pass
• Any time before continuing work, to confirm the workspace is internally consistent

Produces:

1. audit/audit_report.md - findings by severity (P0-P3), scored
2. Mechanical fixes applied in place (with a diff summary)
3. A short AskUserQuestion round for every judgment call

It checks Pureinn artifacts against Pureinn conventions - it does not read the codebase or legacy docs (that is pm-reconcile / pm-reverse-extract).

Position vs. related skills

pm-reconcile and pm-reverse-extract hand off to pm-audit as their verification step.

What this skill does NOT do

• Read the codebase or legacy documents (that is reconcile / reverse-extract)
• Change business decisions or rule values - only structure, naming, references, and conformance. Tier 2 may report a strategic contradiction, but it never resolves it - resolving means choosing between two business claims, which belongs to the authoring skill in delta mode.
• Generate new artifacts that do not exist - it audits what is there (a missing artifact is a finding, not something it invents)

Dependencies

• A Pureinn workspace exists: pureinn-workspace/[project-slug]/ with at least state.json and some artifacts.

If no workspace is found, do not guess. Tell the user to run /pureinn first (greenfield) or /pm-reverse-extract / /pm-reconcile (existing product).

Scope (whole workspace or one area)

pm-audit takes an optional area argument, mirroring pm-reconcile's per-area model:

Tier scoping: area scopes (domain, rules, features, open-questions) run Tier 1 only. strategy runs Tier 2 only. The default whole-workspace run does both tiers.

When an area is given, scan and report only that area's artifacts (plus their direct cross-references - e.g. features checks that BR-IDs in cards resolve into business_rules.md, without auditing the rules themselves). When no area is given, audit everything. If the user states a scope in plain language, honour it (per the Adaptive-execution standard).

Step 0: Locate workspace + detect version

Determine the scope first (from the argument or the user's request - default whole workspace). Then find the workspace and inventory the artifacts in scope:

Version-drift signals (detect an older-framework workspace). This is the concrete migration checklist - an artifact produced by an older Pureinn version will carry one or more of these; scan for each literally, not just "convention drift" in the abstract:

• Old lifecycle state names (1_Walkthrough, 2_Design, 3_Design_Inspection_Passed, 4_Build, 5_Code_Inspection, 6_Promoted_to_Build)
• Old hierarchy terms (Subject Area, Major Feature Set) or bare FS-ID without FS-NN: Name
• Missing newer Feature Card fields (feature_set, estimate) or the ## Subtasks section
• Notion cache key notion.* instead of notion_ids.*
• Feature Card prd_ref pointing at the old PRD path - prd_ref: /product/PRD.md#... (or the missing-slash variants product/PRD.md#... / bare PRD.md#...). Older versions saved the PRD as PRD.md; the canonical save path is now product/PRD_master.md, so every old card carries a dead reference to a file that no longer exists. Migrate to prd_ref: /product/PRD_master.md#... (preserve the #section anchor). Initiative-PRD refs (/initiatives/[slug]/prd.md#bc-...) are a separate valid form - leave them.
• A separate MVP-membership field (mvp: true/false, roadmap_phase:, or an "MVP" column) instead of the single canonical phase axis
• layer: fullstack instead of the explicit layer set (frontend, backend, system)
• Reconcile-reality words (Built / In Progress / Backlog) sitting in a status/Status field instead of a canonical lifecycle value

Interaction: Group related questions (2-4 per round) and confirm before moving on. For any A/B/C/D choice, use the AskUserQuestion tool with one option marked (Recommended) - never print options as plain text. Keep open-ended questions free-text (don't fake options). If the user is unsure, propose 3-4 concrete options plus "Other". Surface an assumption the moment you make one; never fabricate to fill a gap. (Full standard: CLAUDE.md.)

Step 1: Scan

Read every artifact in scope (Step 0) and run the checks below - for an area scope, only that area's artifacts and their direct cross-references; for whole-workspace, all of them. Collect findings; do not fix yet.

Content truncated.