Tempo Harness

Appearance

qa-philosophy ​

qa-philosophy

qareadhands-off

Use this when: you want the docs reconciled against the code

Problem it solves — Docs drift from the code they describe. This reconciles what CLAUDE.md, CONTEXT.md, and the rules say against what is actually true, surfacing the contradictions to fix.

Used in workflows: Health Check · Harness health Check

QA philosophy (foundational-doc drift) ​

The docs that underpin every feature drift the moment a decision is made in a chat, issue or PR but never written back. This skill keeps the foundations honest: it reconciles the canonical "why/what" against reality, and — because editing always-on context changes every future session — surfaces proposed edits for you to approve, never writes unprompted.

The two layers ​

Canonical (the underpinning)Reality (what can supersede it)
SOUL.md — persona, voice, valuesdecisions stated in this chat
CLAUDE.md (authored part only) — how the project works, scope, conventionsmerged PRs (gh pr list --state merged)
CONTEXT.md — domain definitionsissues (closed = done/changed; open = redirected intent)
docs/adr/ — decisions + rationalethe code as actually built
.claude/rules/ — conventionsdocs/learnings/ entries

Never touch the auto-generated <laravel-boost-guidelines> block in CLAUDE.md — boost:update regenerates it, so edits are lost. Audit only the authored portion.

The drift shapes — this is the skill ​

Loading the two layers is setup; the value is in the cross-check. For each canonical statement ask what reality says and flag where they part:

  1. Superseded — an ADR or CLAUDE.md rule a later PR/issue/decision overrode (e.g. ADR-0002 set approach X; PR #N changed it). ADRs are append-only history — mark the old one Superseded by ADR-000X and write the new ADR; do not rewrite the original.
  2. Contradicted — the code now does the opposite of a stated principle (a job that does silently skip; a value duplicated in the DB that CONTEXT.md says is Todoist-only).
  3. Stale — points at something gone or renamed (a removed module, a shipped scope item still listed as TODO, a path/casing that no longer matches — e.g. soul.md vs SOUL.md).
  4. Unrecorded — a decision made in chat/issue/PR that belongs in a canonical doc but isn't there. This is the common one after you've just explained new intent: find its right home and fold it in.
  5. Internally inconsistent — two canonical docs disagree (CLAUDE.md says one thing, CONTEXT.md another).

Whether a whole doc (or section) still earns its place — consolidate, simplify, or remove it, and the always-on token cost — is optimise-context's call (its doc-set-rationalise + footprint lenses). When a drift finding makes you suspect a doc is now redundant, flag it and hand it there; this skill fixes accuracy, not footprint.

The harness glossary (docs/agents/glossary.md) and its flat term index in CLAUDE.md are canonical too. When a chat / PR / decision pins a new harness term or shifts what an existing one means, reconcile it here — add or correct the definition and keep the CLAUDE.md index in sync (the index is the always-on lookup; the glossary holds the meanings).

Workflow — surface, then write ​

  1. Pick the mode.
    • Reconcile — you just added/clarified intent: take that input as the source and find which canonical doc(s) it belongs in, plus anything it now contradicts.
    • Audit — a periodic sweep with no new input: walk the canonical layer against reality.
  2. Load reality selectively — recent merged PRs, recently closed/changed issues, recent commits to the relevant area, and docs/learnings/. Don't boil the ocean; scope to what the canonical claims touch. In Audit mode the per-doc cross-checks are disjoint reads — they may fan out per docs/agents/orchestration.md (one read-only scout per canonical doc, briefed with that doc + where reality 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 above. For each finding gather: the canonical statement + its file:line, what supersedes/contradicts it + evidence (PR #, issue #, commit SHA, file:line, or "your message just now"), and the proposed edit (or the ADR-supersession move).
  4. Present, don't write. List findings with that context and AskUserQuestion (multi-select) which to apply. Never edit a canonical doc unprompted — these load into every session. It's fine to find nothing aligned-and-current — say so.
  5. Apply only the confirmed ones. Keep edits tight and in each doc's voice (SOUL.md is persona prose; CLAUDE.md is terse directives; ADRs get a status line + a new record). For an Unrecorded decision worth a rule, route it through find-learnings → .claude/rules/ rather than bloating CLAUDE.md.
  6. Report what changed and where, and anything left with the reason.

Where it sits ​

  • Not optimise-context (token footprint + whether a whole doc earns its place). This fixes accuracy; that trims cost. They pair: reconcile here, then trim there.
  • Not find-untracked-work (missing work → files issues) or find-learnings (a tactical lesson → memory). This is the strategic/foundational layer → canonical docs.
  • Chains to qa-wiki — the public wiki (harness-dashboard) re-tells these foundational docs, so it drifts when they change. Once the source is reconciled here, end by running qa-wiki to propagate the change to the hand-authored wiki pages.
  • Not check-reasoning (red-teams a plan or diff). This audits the standing context.
  • Pairs naturally after a big merge or a context-setting chat; run it before planning a phase so you're building on current foundations.

How this gets triggered ​

Mostly you'll invoke it directly — "I've told you something new about Tempo, reconcile it" / "is our philosophy still accurate?". There's no clean tool-event for "the user clarified intent", so it's description-driven by design rather than hook-fired. A sensible cadence: after each significant PR merges, and at the start of a new phase.