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.

Artifact language

Checks state.json → artifact_language. Default (unset or "English"): no change in behavior.

• If set to a non-English language: write prose content (descriptions, rationale, rule text) in that language.
• Never translate: IDs, frontmatter keys and enum values, section headers other skills parse, file names - these stay English always, regardless of the setting.

Standalone run

Needs the artifacts listed under Dependencies - it synthesizes them, so without them there is nothing to synthesize.

• No workspace, or inputs missing: name which are missing and what each one unlocks, then offer the PREREQ paths - proceed on stated assumptions marked [ASSUMED - what/why], or route to the skill that produces the missing input. Never hard-block, and never invent the input.
• Writing never depends on /pureinn having run: with no workspace, create just the folder this skill writes into, or write to a path the user names, and say where the file went.
• Read pureinn-variables.md / state.json where a value is actually used, not at the top of the run. Missing value: continue and name the capability it costs.

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
• Feature Card at status ≥ 2_Spec_Done without a ### Edge Case Coverage table (pre-5.62.0 card). Do NOT migrate it in the audit - that means writing acceptance criteria, which the audit must never invent. Route each card to /pm-feature-design [FEAT-ID] --edge-cases, ordered by status: 3_Ready_to_Build and 4_In_Build first, then 5_In_Review, 2_Spec_Done / 2b_In_Design, and 6_Shipped last. Severity: P2 for 2_Spec_Done-5_In_Review; P3 for 6_Shipped (a retro table only records gaps, it changes no shipped behavior - on a Rebuild workspace do not let dozens of these bury the active cards)

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.

The table above is Tier 1 (form). For a whole-workspace run or /pm-audit strategy, also run Tier 2 below.

Tier 2: Strategic consistency (read-only, cross-artifact)

Does NOT check form - checks whether the strategic layer's content still agrees with itself and with the research it was built on. It never auto-fixes (changing a value prop or a segment is a business decision). It surfaces each conflict and routes the fix to the authoring skill, which re-runs in delta mode.

Read the strategic artifacts that exist - product/PRD_master.md, roadmap, personas.md, customer-segments.md, market-analysis.md, business-model-canvas.md, feature_list.md - and check these cross-artifact pairs:

For each conflict, record: [CONFLICT] Artifact A says X (location) / Artifact B says Y (location) → route: /pm-[skill]. Do not resolve it - the authoring skill resolves it against real evidence in delta mode. If a referenced strategic artifact is absent, note it as "not present - check skipped", do not invent it.

Step 2: Audit report

Save to: pureinn-workspace/[project-slug]/audit/audit_report.md

Score and group every finding by severity:

# Workspace Audit - [Product Name]
> Generated: [date]  By: pm-audit v[version]
> Workspace: pureinn-workspace/[slug]   Framework target: v[current]

## Score: [N] findings - P0:[x] P1:[x] P2:[x] P3:[x]

## P0 - Broken
| ID | Finding | Location | Fix |
## P1 - Drift
## P2 - Missing structure
## P3 - Cosmetic

## Version migration (if drift detected)
[what older-version patterns were found and the migration applied/proposed]

## Prototypes (report-and-route - not auto-fixed)
[If none: "No prototype folders" or "Prototype hygiene clean."]
| Prototype / card | Finding | Detail | Route |
|---|---|---|---|
| prototypes/[name]/ | Decision: open | Purpose: [test / workbench] · open [N] days since [Created] / no Created date | `/pm-prototype` |
| [location] | PRT- ID in production register | [PRT-ID] at [file + line/field] | `/pm-prototype` |
| [FEAT-ID] | promoted_from does not resolve | [PRT-ID] - not in any feature-plan-prt.md / folder missing | `/pm-prototype` |
| prototypes/[name]/ | workbench feature with no phase | [PRT-ID] built, no phase | `/pm-prototype` |

## Strategic consistency (Tier 2 - read-only, not auto-fixed)
[If clean: "No strategic conflicts - the strategic layer is coherent."]
| Conflict | Artifact A (says) | Artifact B (says) | Route fix to |
|---|---|---|---|
| [check name] | [claim + location] | [claim + location] | `/pm-[skill]` |

Tier 2 conflicts are listed separately and are not scored P0-P3 - they are not mechanical findings and are never auto-fixed. They are routed, not resolved.

Present the score, P0/P1 summary, and any Tier 2 conflicts to the user before fixing.

Step 3: Fix

• Mechanical (auto-fix): ID format normalization, old → new lifecycle state names, missing feature_set/estimate/Subtasks scaffolding added, notion.* → notion_ids.*, prd_ref: /product/PRD.md#anchor (and the product/PRD.md / bare PRD.md variants) → /product/PRD_master.md#anchor, anchor preserved (an Initiative-PRD /initiatives/[slug]/prd.md#bc-... ref is left untouched), path-slash convention, layer: fullstack → the explicit layer set derived from evidence, dead-link repair where the target is unambiguous, collapsing a stray mvp/roadmap_phase field or "MVP" column into the canonical phase (one axis). Apply in place; report a diff summary.
• Judgment (ask): anything where the fix changes meaning - a naming anti-pattern rewrite (always propose a concrete client-valued rename, e.g. "Drive order state machine" → "Submit order for matching"; never leave a flagged name unaddressed), an ambiguous dangling reference, a feature that may need splitting, a missing card that may be intentional. Batch these via the grouped AskUserQuestion pattern (CLAUDE.md), 2-4 per round, confirm, apply. The feature_list.md is the whole-list orientation surface - backfill writes there FIRST, for every feature, then mirrors to the card and Notion. Do not fill individual cards while leaving the list incomplete - the list is what the team reads to understand the backlog at a glance. Every feature in the list must end up with a Description and the full property set; iterate across the whole list, not card-by-card in isolation.
• Missing / weak descriptions (backfill from evidence): for every feature whose Description is missing OR too terse (a few words / a single clause), draft a proper one from the card's Evidence / code references / linked rules: 2-3 clear, genuinely orientational sentences - what it does, who uses it, the value/role. Not a one-liner restating the title. Batch via AskUserQuestion, then write to the feature_list.md entry AND the card's ## Description. The list entry can be a tight 1-2 sentences; the card carries the fuller version - but neither is blank or trivial.
• Missing / inconsistent feature metadata (backfill) - for the WHOLE list: for layer, phase, kano, vxc, has_subtasks on every feature:
  • has_subtasks → mechanical: true only if the Subtasks section has a real item - ignore italic/placeholder lines (*TBD ...*, the - [ ] [nuance...] template line). Empty/placeholder → false.
  • layer → derive from evidence (FE routes/components → frontend, controllers/services → backend, jobs/cron/integrations → system), confirm in batch.
  • phase, kano, vxc → propose with reasoning and confirm via AskUserQuestion (a 6_Shipped feature is usually KANO Must-be; phase from the roadmap / MVP flag if present - for a coherent phase split across the whole list, align to pm-product-roadmap). Never silently guess KANO/V×C - they are planning judgments. Write confirmed values to the feature_list.md entry, the card frontmatter, and Notion - keep all three in sync (the v4.11.0 parity rule). The list is not done until every feature carries the full set.

Never silently change a rule value, an acceptance criterion, or a business decision - those are out of scope (route to pm-feature-design / pm-business-rules-library). This includes the Edge Case Coverage table: a missing table, a TBD cell or a missing edge case AC is routed to /pm-feature-design [FEAT-ID] --edge-cases, never filled here. Only the tag mismatch is mechanical - an AC referenced for EC-CONC whose title lacks [EC-CONC] gets the tag added.

Prototype hygiene findings are report-and-route - fix nothing, invent nothing. Every one of them is a decision that belongs to /pm-prototype: an open prototype needs its kill / promote / partial decision; a PRT- ID in a production register is either a promotion that was never run (it needs a real FEAT-ID through promotion) or a leak to remove; a dangling promoted_from: needs the owner to say what happened to the prototype; a workbench feature with no phase needs a phase or a cut with its reason. Never close a prototype's Decision, never rename a PRT- ID to an invented FEAT-ID, never delete a promoted_from: line to make the reference "resolve", never assign a phase, and never edit anything inside a prototype folder. List the finding with its route and stop.

Tier 2 (strategic consistency) is report-only. Never auto-edit PRD / roadmap / personas / market / business-model content to resolve a strategic conflict - choosing between two strategic claims is a business decision. List each [CONFLICT] with its route and stop. The user runs the routed authoring skill (which re-runs in delta mode) to resolve it against real evidence. Auditing must not silently pick a winner.

For version migration: show the old→new mapping, confirm once, then apply across all affected artifacts in one pass.

Step 4: Re-verify + summary

Re-run the Step 1 scan on the fixed workspace. Confirm P0/P1 are cleared (or list what remains and why).

AUDIT COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Before:  P0:[x] P1:[x] P2:[x] P3:[x]
Fixed:   [N] mechanical, [N] confirmed via questions
Remaining: [N] (listed in audit_report.md with reason)
Prototypes: [N] findings routed to /pm-prototype / clean / none
Version:  [migrated from vX / already current]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Save to

pureinn-workspace/[project-slug]/audit/audit_report.md   (this skill)

Plus in-place fixes to the affected artifacts (registers, feature_list, Feature Cards, state.json).

Handoff

Čo si teraz má: Workspace zladený s konvenciami (Tier 1) a obraz strategickej koherencie (Tier 2) - opravené ID/naming/refs/lifecycle + zoznam strategických konfliktov s routovaním.

Ďalší krok:

• Ak Tier 2 našiel [CONFLICT]: spusti routovaný authoring skill (/pm-prd, /pm-product-roadmap, /pm-business-model...) - opraví to v delta mode voči reálnym dátam. Audit ich nerieši.
• Ak audit našiel nález pri prototypoch (otvorený prototyp, PRT- ID v produkčnom registri, neplatné promoted_from:, workbench feature bez fázy): /pm-prototype - rozhodnutie patrí tam, audit ho nerobí.
• Ak je čisto: /pm-stripe — pokračuj v JIT delivery. Alebo /pureinn pre phase gate check.

Môžeš preskočiť ak: Workspace práve vznikol aktuálnou verziou frameworku a strategická vrstva sa od poslednej validácie nezmenila - drift ani strategický konflikt neexistuje.