promode-audit

What this skill does

You (the main agent) run this audit: fan out parallel assessors, one per dimension, then synthesise their findings into a prioritised, actionable plan. The assessors gather evidence; the **prioritisation and plan are yours** — that judgement is not delegated.

This audits the **repo's alignment with promode's working practices**, plus a pre-flight setup check. promode ships its delivery via its own plugin SessionStart hook, so nothing is installed per-project — the only setup issue to catch is *stale* leftovers from the retired copy-install.

Each dimension is a **reusable lens, not just a step in the full sweep** — it mirrors what a working agent is already responsible for. The same standard runs at three cadences: every agent upholds its dimension *continuously* while working; a single owning agent can be asked to audit just its dimension for a *targeted* spot-check (e.g. `promode:code-reviewer` for tests or architecture); or you run this skill for the *full* parallel sweep. Auditing and doing are the same standard, zoomed differently.

<process>
1. **Frame** — Skim `CLAUDE.md` and `README` to understand the repo (language, stack, size, test setup). Pick which dimensions apply and scale the assessor count to the repo (a small library may merge dimensions; a large system warrants all of them, possibly split by area). Also do a quick **setup check**: the promode plugin delivers its brief via its own SessionStart hook, so a project needs nothing installed — flag any stale leftovers from the retired per-project copy-install (`.claude/PROMODE_MAIN_AGENT.md`, `.claude/hooks/promode-main-context.sh`, or a promode `SessionStart` entry in `.claude/settings.json`); they now double-inject the brief and should be removed.
2. **Fan out assessors in parallel** — Dispatch one background agent per dimension using the standard fire-and-forget pattern (all in one turn, then end the turn; their `<task-notification>`s wake you). Each is **read-only — instruct it to modify nothing**. Give each the assessor brief below. Wait for all to report.
3. **Synthesise** — Merge findings into one assessment and a single prioritised plan (format below). Resolve overlaps between dimensions; rank across all of them.
4. **Deliver & offer to capture** — Present the report. Offer to turn the plan into tracked work (e.g. `KANBAN_BOARD.md` / `IDEAS.md`) or a saved report file.
</process>

<dimensions>
The promode-alignment axes. Each is one assessor's deliverable.

| Dimension | Assesses (promode principle) | Suggested assessor |
|-----------|------------------------------|--------------------|
| **Framing & traceability** | Apply the **framing & traceability check** (below): does a top-down document hierarchy (goals/risks/priorities, realistic customer profiles / personas → marketing → feature definitions → feature tests) make the repo self-describing, each layer explaining WHY and linking up to a goal? Are the **user needs/journeys/workflows** features rest on cited or flagged as assumptions (a silent one is the highest-severity finding) vs asserted as fact? *(feature knowledge-base, self-describing repo, evidence-based user needs)* | `general-purpose` |
| **Tests & feedback loops** | Behaviour-focused tests on critical paths; tested through public interfaces vs coupled to implementation / over-mocked; speed & determinism (can an agent get a fast pass/fail signal?); a documented one-command way to run tests, lint, typecheck, and the app. Where a UI fronts real logic, apply the **Discovery → Determinism layered-coverage check** (below) — including whether the acceptance tier reads as **domain-language user stories traceable to a cited/flagged need** and whether a **product-doc↔acceptance-test seam** exists (tool-agnostic, not BDD-mandated). *(TDD, tests-as-documentation, fast feedback, verifier-readiness, traceable acceptance)* | `promode:code-reviewer` (opus) |
| **Agent knowledge & orientation** | Apply the **CLAUDE.md health check** (below). Beyond it, two questions: (1) **capture** — is durable reusable knowledge **captured as linked nodes reachable from `CLAUDE.md`, or left tribal** — across the kinds the knowledge-graph model names: subsystem orientation, non-obvious build/run gotchas, **decisions** (ADR-style), and **runbooks** (repeatable operational procedures — deploy, migration, env bring-up, recovery, recurring incidents)? Flag any kind that's missing, unlinked, or lives only in someone's head. (2) **discoverability** — are **crucial design constraints** (invariants, prohibitions, required patterns, load-bearing decisions) stated *inline* in `CLAUDE.md`, or only reachable by a traversal an agent may never make? The latter is the dimension's highest-severity finding (see the health check). *(CLAUDE.md-rooted knowledge graph; decision/runbook/operational-knowledge capture; critical-constraint discoverability)* | `general-purpose` |
| **Architecture & navigability** | Module depth vs shallowness; testability (dependency injection, seams, return-values over side-effects); oversized files that burn agent context; tangled coupling, dead code, misleading names. *(small diffs, testability, context-frugality)* | `promode:code-reviewer` (opus) |
| **Observability & traceability** | Apply the **observability & traceability check** (below): do runtime logs carry a correlation/tracer ID that threads one request client→backend (and across service hops), filterable on both sides, so an agent can pull a single request's whole trace instead of slurping unfiltered logs? *(context is precious applied to runtime; cheap agent debugging)* | `promode:code-reviewer` (opus) |
| **Design system & visual feedback loop** | Apply the **design system & visual feedback-loop check** (below): is a design source-of-truth established (two-layer `DESIGN_SYSTEM.md`, tokens + rationale, linked from `CLAUDE.md`, traceable to personas/goals), does a lookbook exist and cover the components/screens, and is there a live-refresh preview loop for design + marketing artifacts? *(visual feedback loop = the design analogue of the operator-seam test loop; crystallise taste into determinism)* | `promode:product-design-expert` |
| **Change hygiene** *(optional)* | Commit focus & size; messages explain *why*; do tests land with the code they cover? *(small focused commits, explain-why, visible TDD)* | `general-purpose` |
</dimensions>

<framing-traceability>
The repo should be **self-describing top-down** — a reader (human or agent) can start at the high-level goals and follow links down to the tests that implement them. The Framing & traceability assessor checks:

1. **The hierarchy exists** — are there docs for high-level goals/risks/priorities, realistic customer profiles / personas (`docs/product/PERSONAS.md`), product/marketing framing, feature definitions, and feature tests? Note which layers are missing or thin.
2. **Every layer explains WHY and links up** — each artifact states *why* it exists and links to the layer above, ultimately to a goal. Flag docs that describe only WHAT/HOW with no WHY, and layers that don't connect upward.
3. **No orphans, no drift, no sprawl** — can each significant feature be traced up to a goal? Flag orphaned features (no link to any goal → likely superfluous, or the goals doc is stale) and goals nothing implements. Also flag **goal sprawl** — an unfocused or ballooning goals/risks/priorities list, or goals that look invented post-hoc to justify a feature; too many goals is itself a finding (focus is the scarce resource). A broken chain is a **diagnostic signal**, not just a missing file — say which interpretation is likely and recommend the fix (cut the work, sharpen the goal, or update a *genuinely* stale goals doc).
4. **User-facing features trace to a realistic persona** — can each user-facing feature name the documented customer profile / persona it serves? Flag features with no persona (who is this *actually* for?) and personas that look invented or flattered to justify a feature