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

Skill	Input → output
pm-reconcile	codebase vs legacy docs → reconciled rebuild
pm-reverse-extract	codebase → feature inventory
pm-audit	Pureinn artifacts vs Pureinn conventions → drift/error fix

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:

Command	Audits
/pm-audit	Whole workspace (default) - all artifacts
/pm-audit domain	domain/entities.md + domain/domain-model.md (structure, entity/state naming, ERD ↔ entities consistency)
/pm-audit rules	domain/business_rules.md + domain/decision_models.md (BR/TBL IDs, rule↔entity refs, decision-table completeness)
/pm-audit features	features/feature_list.md + features/cards/ (card structure, FS-NN, Section-1 BR-ID refs resolve, lifecycle status)
/pm-audit strategy	Tier 2 only - cross-artifact strategic consistency (PRD ↔ personas ↔ roadmap ↔ market ↔ business model ↔ feature phases). Read-only, routes fixes to authoring skills.
/pm-audit [other]	any single artifact the user names

Tier scoping: area scopes (domain, rules, features) 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:

Artifact	Present?
state.json
domain/entities.md, business_rules.md, decision_models.md
features/feature_list.md + features/cards/
product/PRD_master.md
roadmap, glossary

Version-drift signals (detect an older-framework workspace):

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

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.

Dimension	What is checked
Structure	Feature Cards match the canonical template (sections 1-4 + Subtasks; frontmatter: id, title, status, stripe, feature_set, actor, owner, priority, estimate, prd_ref, feature_flag, flag_default). Registers match current format and header.
ID & naming	FEAT/BR/TBL/FS IDs well-formed (FEAT-[DOMAIN]-NNN, BR-[DOMAIN]-NNN, TBL-[DOMAIN]-NN, FS-NN) and unique. The naming check is mandatory and must actually run over every feature name - report its result explicitly (even "0 anti-patterns found") so a silent skip is visible. Each name must be <action verb> <result> <object> with a strong verb and an object = a domain entity. Flag every violation: (a) vague/banned verbs Process / Manage / Handle (and similar non-specific verbs); (b) technical objects - the object is an implementation construct not a domain entity (e.g. "...state machine", "...FSM", "...queue", "...flag", "...handler"); (c) the other FDD anti-patterns (bundled multi-op, missing object, CRUD-as-feature, etc.). A naming anti-pattern on an active feature is a P1 finding. Report each as [FEAT-ID] "name" → [which anti-pattern] → suggested rename.
Cross-references	Every BR-ID / TBL-ID / entity link in a Feature Card resolves to the register. feature_set matches feature_list. stripe is a real stripe. No dangling links.
Lifecycle	status is one of the canonical states (1_Backlog, 2_Spec_Done, 2b_In_Design, 3_Ready_to_Build, 4_In_Build, 5_In_Review, 6_Shipped) everywhere - frontmatter, feature_list, and Notion use the same single vocabulary. No orphaned or invalid states. 2b_In_Design is valid only for a feature whose layer includes frontend - a pure backend/system feature in 2b_In_Design is drift (P2: it has no UI to design). Reconcile-reality words (Built / In Progress / Backlog) are NOT status values - if a feature_list or Notion Status still carries them, that is drift: map to canonical (Built→6_Shipped, In Progress→4_In_Build, Backlog→1_Backlog) and keep the reality word only as a human label in the card's Current state (extracted) section. Mixed vocabularies on the status axis = P1.
Version drift	Any of the Step 0 drift signals → migration finding.
Completeness	Every feature in feature_list has a card; every card has its required sections; registers are initialized; state.json flags match reality.
Description present	Every feature has a non-blank Description - both its feature_list.md entry and its card's ## Description section, for every status (including 6_Shipped lean stubs and 1_Backlog). A feature with no description is a P2 finding (orientation gap).
Feature metadata complete	Every feature carries the full property set in frontmatter + feature_list + Notion: layer (frontend/backend/system), phase (MVP/MVP+/Phase 1... or the project's P0/P1…), kano, vxc, stripe (Dev Stripe), has_subtasks. Also check value consistency: has_subtasks matches whether the card's Subtasks section actually has items; values are from the allowed sets. layer is one or more of {frontend, backend, system} (a cross-layer feature lists several, e.g. frontend, backend) - flag any value outside the set, especially fullstack (not a layer → replace with the actual layers), P2. Missing or in

---

Content truncated.