qa-wiki

qa-wiki

qawriteshands-on

Use this when: the wiki has drifted from the harness

Problem it solves — The public harness wiki drifts the moment the harness changes but its hand-written pages don't — a stale count, a renamed skill, a wrong threshold. This audits those narrative pages against the live harness and reconciles each drift on confirm, then rebuilds to prove the links still hold.

QA wiki (hand-authored-page drift)

The harness wiki (harness-dashboard/) is the public face of the harness. Most of it can't drift — the skills/rules/agents/hooks/glossary/taxonomy/workflows/learnings pages are regenerated from .claude/ + docs/ on every build. The drift surface is only the hand-authored narrative: harness-dashboard/philosophy/*.md and harness-dashboard/index.md. Those make prose claims about the harness ("six agents", "mutation ≥ 90%", "the five pillars") that go stale the moment the harness changes but the narrative doesn't. This skill keeps that retelling honest.

Two floors, this is the top one

1. Mechanical (build-time, free) — the dashboard drift-check (harness-dashboard/scripts/drift-check.mjs) fails the build if a hand-authored page links a skill/agent that doesn't exist. Renames and removals are caught there automatically; you don't run this skill for those.
2. Reasoning (this skill) — the semantic drift the build can't see: wrong counts, stale thresholds, a list that's grown, a superseded claim, a new concept the narrative never absorbed. This is the skill — the value is the cross-check of each prose claim against the live harness, not loading the pages.

The canonical layer vs the pages

Hand-authored page	Reconcile against (the live harness)
philosophy/overview.md	the closed-loop skill names; the five pillars; the spine clauses
philosophy/pillars.md	the pillar set + each pillar's owning skill (config/harness.php, .claude/skills/)
philosophy/guardrails.md, gates.md	the Definition of Done thresholds in CLAUDE.md (coverage, mutation, the ci:check vs mutation split)
philosophy/security.md	docs/security/threat-model.md (boundaries, the gate split)
philosophy/agents.md	.claude/agents/ roster + read_only_agents in config/harness.php
philosophy/memory.md, anatomy.md, brainstorm.md	docs/learnings/ shape; the skill anatomy; the brainstorm skill
index.md (hero/cards prose)	counts come from stats.data.mjs (live) — but the prose framing is hand-written
the docs/agents/glossary.md index → wiki	a term whose meaning shifted

The single most common drift: a count or a name (agents 3→6, a renamed skill, a threshold 90→95) — check those first, they're the cheapest to verify.

The drift shapes

For each prose claim, ask what the harness actually is now and flag where they part:

1. Stale count / threshold — "three agents" (there are six); "mutation ≥ 90%" (it's 95%, and it's a separate gate, not in ci:check).
2. Renamed / removed — names a skill/agent/pillar that's gone or renamed (the mechanical floor catches a broken link; this catches a stale mention in prose the link check misses).
3. Superseded — a claim a later harness decision overrode (a pillar reframed, a gate added, a rule changed).
4. Unabsorbed concept — a new harness concept (a new gate type, a new pillar, a new agent role) the relevant narrative page never picked up.
5. Internally inconsistent — two wiki pages disagree, or a wiki page disagrees with CLAUDE.md / the glossary.

Workflow — surface, then write, then verify

1. Scope. Default: all philosophy/*.md + index.md. Or a single page if you know where the change landed (e.g. you just added an agent → agents.md).
2. Load reality selectively — the live source the page claims about (the roster, the config thresholds, CLAUDE.md, the glossary). Don't boil the ocean. The per-page cross-checks are disjoint reads — they may fan out per docs/agents/orchestration.md (one read-only scout per page, briefed with that page + where its truth lives), candidate findings merged per docs/agents/deterministic-merge.md; the drift judgement, present and apply stay in-thread.
3. Cross-check for the five shapes. Per finding gather: the page claim + file:line, what the harness actually is + evidence (.claude/agents/ count, config/harness.php value, a CLAUDE.md line, a PR #), and the proposed edit.
4. Present, don't write. List findings with that context and AskUserQuestion (multi-select) which to apply. Never edit a page unprompted. It's fine to find nothing — say "in sync" and stop.
5. Apply the confirmed ones in the page's voice (these are narrative prose, not terse directives — keep them readable, plain-first).
6. Verify — cd harness-dashboard && npm run build (runs generate → the drift-check → build). Green proves no broken links remain and the page still compiles. Report what changed and where.

Contract

• Task class — qa-: audit a concrete artifact (the hand-authored wiki pages), surface findings, write only on confirm (these are public docs; surface-then-confirm).
• Allowed tools — Read/Grep/Glob over harness-dashboard/philosophy/, .claude/, config/harness.php, CLAUDE.md; Edit only on confirmed findings; Bash for npm run build to verify.
• Direct vs fork — in-thread by default; the per-page cross-checks MAY fan out to read-only scouts (above) when auditing the full set.
• Verifiable artifact — every confirmed finding fixed in its page, and npm run build (generate → drift-check → build) green.

Where it sits

• Not qa-philosophy — that audits the source foundational docs (CLAUDE.md/SOUL.md/CONTEXT.md/ADRs) ↔ code. This audits their public retelling in the wiki. They chain: qa-philosophy reconciles the source, then calls this to propagate to the wiki.
• Not the dashboard drift-check — that's the mechanical floor (broken skill/agent links fail the build). This is the reasoning audit on top.
• Not optimise-context (token footprint of always-on docs) — the wiki isn't always-on context; this fixes accuracy.

How this gets triggered

Mostly description-driven — "the wiki's drifted", "is the agents page still right?". There's no clean tool-event for "a hand-authored page went stale", so it's not hook-fired. Sensible cadence: after any harness change that touches a skill/agent/pillar/threshold, and as the final propagation step once the source docs are reconciled.