Pouya LajevardiandClaude Opus 5
8f1df2c27c
Separated from the step 1 feature commit on adversarial-reviewer's own recommendation: instructions that narrow a reviewer's scope should not travel in the same commit as the work that reviewer is checking. claims-auditor.md — REMOVE the enumerated membership list. It read "ADRIC, ADRIO, OBA sections only" while AGENTS.md §4 had gained the Canadian Tax Foundation that morning, so the auditor's own brief contradicted the register: it would have flagged a verified membership as unverified and would not have noticed CTF being dropped. This file has now hosted a stale claim twice. Replaced with an instruction to read the §4 row at audit time — a copy of a fact goes stale where nobody re-reads it. adversarial-reviewer.md — state that Lighthouse cannot be run until step 7 and that its absence is not a finding (AGENTS.md §7, R11). Repair a sentence left truncated mid-list. Caveat the "~1 MB of logo PNGs" figure against Q34, which is open on it. build.md — Phase 4 now carries the measurement that justifies the re-review requirement: on the Astro 5→7 upgrade four of six second-round findings were defects in the first round's own fixes. Phase 5 gains a grep asserting no `animation` shorthand beside `animation-timeline` survives into dist — Lightning CSS folds them into an invalid declaration that works in dev and is dead in the build. That happened twice in one session, the second time inside the fix for the first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012XquaEq4BgWMCwUqLEyNkF
5.0 KiB
description, argument-hint
| description | argument-hint |
|---|---|
| The standing execution loop for this repo — plan, implement, adversarial review, resolve, verify, record. Use for every substantive change. | <what to build, e.g. "the /med-arb/ page" or "step 4 of the build order"> |
ultrathink
Task: $ARGUMENTS
Execute the six-phase loop below. Do not skip a phase because the task looks small — the loop is the quality mechanism, not ceremony. If a phase genuinely does not apply, say which and why before moving on.
Phase 1 — Plan (think hard before writing anything)
- Read
AGENTS.mdin full if you have not this session. Read §12 Standing Reminders and surface anything live to Pouya before you start. - Read the specs in
docs/that bear on this task. - Restate the task in your own words, and name:
- which locked decisions (D1–D18) it touches
- which specs govern it
- which facts it needs from the §4 Verified register
- Stop and ask if you find a conflict — between the task and a locked decision, between two specs, or between the task and a fact you do not have. A blocked build is a correct build. Never resolve a conflict by guessing, and never soften a claim to make it defensible.
- State your plan before implementing.
Phase 2 — Implement
Follow CLAUDE.md conventions. Zero JavaScript by default. Tokens only, no raw
hex, no magic numbers. Semantic HTML. Every page gets its metadata.
Where you need a fact you do not have: TODO(pouya): <the exact question> in the
source and a new numbered question in AGENTS.md §9. Do not invent it.
Phase 3 — Adversarial review (this is not optional)
Invoke both review agents on the change, in parallel:
adversarial-reviewer— correctness, accessibility, crawlability, performance, security, simplicityclaims-auditor— every factual assertion traced toAGENTS.md§4
Give them the diff and the specs. Do not give them your reasoning for why the work is correct. Your rationale anchors the reviewer and produces agreement instead of review. They form their own view from the artefact; that independence is the whole point of the phase.
If the change touches no user-facing copy, claims-auditor may be skipped — say
so explicitly.
Phase 4 — Resolve
For every finding: fix it, or decline it with a stated reason. Silence is not a response. A declined finding is recorded in the Change Log with the reasoning, so a later reader can see the judgement was made rather than missed.
If you fix anything material, re-run Phase 3 on the fix. A patch written under review pressure is exactly where the second defect lives.
This is not ceremony, and here is the measurement. On the Astro 5 → 7 upgrade (
AGENTS.mdentry (t), 2026-08-26) the second review pass returned six findings. Four of the six were defects in the first round's own fixes — including a date validator whose replacement silently rolled2026-02-30forward to2026-03-02, and a title rule whose fix rejected all five planned launch articles. None of the four existed before the review started. Skip the re-review and you ship the repair, not the bug.
Phase 5 — Verify — run it, do not assert it
npm run check
npm run build
Then, as applicable to what changed:
-
Serve
dist/and confirm the page renders its full content with JavaScript disabled — the failure this whole project exists to fix -
curlthe built HTML and confirm real content, not a shell -
Lighthouse mobile ≥ 95 on all four categories— UNAVAILABLE.@lhci/cliwas removed on 2026-08-26 and is not re-added until build step 7 (AGENTS.mdR11, §7). Report it as not run, tool unavailable. Do not substitute a manual DevTools run and describe it as the same check -
Every internal link resolves
-
Metadata present: unique title, description, canonical, OG, JSON-LD
-
No scroll-driven animation was eaten by the minifier. This must return nothing:
grep -rE 'animation:[^;}]*(scroll\(\)|view\(\))' dist --include='*.css'A hit means an
animationshorthand was written besideanimation-timelineand Lightning CSS folded them into an invalid declaration, which the parser then discards. The effect works innpm run devand is dead in the build.
Never report a check as passing that you did not run. "Should pass" is not a result. If you could not run something, say which and why.
Phase 6 — Record
Append a AGENTS.md Change Log entry, newest first: what changed, old → new,
why, and any decision or plan — including declined findings and anything
deferred. Update Current Truth in place where the change made a section stale.
Re-stamp facts you re-checked with today's date.
If the entry claims a change was applied across files, cite the command and paste its output. Write that claim only after reading the output. Recall is not evidence — three entries on this project asserted a completed sweep and instances survived all three.
Then report to Pouya: what shipped, what the review found, what you declined and why, and what remains open.