Pouya LajevardiandClaude Opus 5
6bf1167624
The re-audit of the deploy-guard change surfaced defects well outside the diff, including one that would have broken production mail. docs/05-backend-spec.md had the two SES DKIM sets exactly inverted, labelling the three records that resolve as "orphans" and the three NXDOMAIN records as "Live. Never delete". Entry (j) corrected this in AGENTS.md §7 and the correction never reached docs/05. Since SES has no custom MAIL FROM, DKIM is the only thing satisfying DMARC, so acting on that table would have silently broken intake mail authentication. Also in this change: - .gitea/workflows/deploy.yml gains a guard as steps[0] that fails the run, naming the variable, if AWS_REGION, S3_BUCKET or CLOUDFRONT_DISTRIBUTION_ID is empty — how a Gitea too old for the vars context manifests. Verified fail-closed under bash -e, sh -e and bash -euo pipefail. - AGENTS.md Current Truth: SPF and DMARC recorded as present (Q20), the matching §10 High risk row retired, three duplicate Q rows removed. - docs/reference/AWS-Hosting-Guide.md tracked and given a do-not-execute banner; it was an executable procedure for the architecture D1/D3 replace. - Copy decks: "a working litigator" and "an active litigation practice" replaced with the register's own wording; LegalService JSON-LD replaced with ProfessionalService; tribunal-secretary offers removed per D14; nine stale question blockers swept. - astro.config.mjs: prefetchAll disabled — it injected JS into every page against the zero-JS convention with no decision recorded. - src/data/site.ts: unregistered response-time commitment nulled (Q27); OBA section names downgraded to [assumed] (Q28). - s3:AbortMultipartUpload reasoning corrected to measure ./dist, not the repo. Opens Q27, Q28, Q29. AGENTS.md entry (q) records the full resolution, including the findings declined and why. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012XquaEq4BgWMCwUqLEyNkF
138 lines
5.1 KiB
Markdown
138 lines
5.1 KiB
Markdown
# 08 — How we work
|
|
|
|
`AGENTS.md` D17. Pouya architects. Claude Code implements, then adversarially
|
|
reviews its own work. This is a standing agreement encoded in the repository, so
|
|
it does not need restating in every prompt.
|
|
|
|
---
|
|
|
|
## The short version
|
|
|
|
```
|
|
/build the /med-arb/ page
|
|
```
|
|
|
|
That single command runs: plan → implement → adversarial review → resolve →
|
|
verify → record. It requests deep reasoning, reads `AGENTS.md` and the specs,
|
|
stops if the task conflicts with a locked decision, invokes two independent
|
|
reviewers on the finished diff, resolves what they find, runs the checks, and
|
|
appends the Change Log entry.
|
|
|
|
You do not need to ask for thinking, for review, or for the record to be updated.
|
|
Those are the agreement, not the request.
|
|
|
|
## The three commands
|
|
|
|
| Command | Does |
|
|
|---|---|
|
|
| `/build <task>` | The full loop. Use for every substantive change |
|
|
| `/review [scope]` | The review pass alone, on the working tree or a named scope. Reports; fixes nothing without your say-so |
|
|
| `/wrap` | End of session — updates `AGENTS.md` under its constitution and leaves the tree clean |
|
|
|
|
## The two reviewers
|
|
|
|
Both are defined in `.claude/agents/` and run in parallel on the diff.
|
|
|
|
**`adversarial-reviewer`** reads the code: correctness and edge cases,
|
|
accessibility, crawlability, performance budgets, security, and whether a
|
|
materially simpler correct version exists.
|
|
|
|
**`claims-auditor`** reads the copy against `AGENTS.md` §4 and nothing else. It
|
|
extracts every factual assertion — credentials, roles, numbers, languages,
|
|
locations, capabilities, and the JSON-LD — and traces each to the Verified table.
|
|
Anything untraceable is reported and does not ship.
|
|
|
|
It is a separate agent on purpose. A general-purpose reviewer will happily
|
|
approve elegant code containing a claim that should never have been published,
|
|
because professional-conduct compliance is not what it is looking at. On this
|
|
project that is the highest-stakes failure mode, so it gets its own pass.
|
|
|
|
**Verifying they are loaded.** `.claude/agents/` is the correct location. To
|
|
confirm the agents are live, invoke one directly:
|
|
|
|
```
|
|
Use the claims-auditor agent to audit README.md against AGENTS.md §4.
|
|
```
|
|
|
|
A verdict table back means both are wired. "No such agent" means the frontmatter
|
|
needs looking at.
|
|
|
|
**Both are instructed to treat uncertainty as a defect.** They will sometimes be
|
|
wrong. That is the intended trade: explaining why a finding is mistaken costs
|
|
minutes, and a missed defect on this project's public marketing pages
|
|
costs a great deal more.
|
|
|
|
## The rule that makes it work
|
|
|
|
**The reviewers are given the diff and the specs — never the implementer's
|
|
explanation of why the work is correct.**
|
|
|
|
A rationale anchors the reviewer. Told why something is right, a reviewer looks
|
|
for confirmation and finds it; given only the artefact, it forms an independent
|
|
view. That independence is the entire mechanism. Every other detail of this
|
|
protocol is adjustable. This one is not.
|
|
|
|
---
|
|
|
|
## Writing a task
|
|
|
|
The commands carry the process, so your prompt only needs to carry the decision.
|
|
Short and specific beats long and hedged.
|
|
|
|
**Good:**
|
|
|
|
```
|
|
/build the /med-arb/ page per docs/01-architecture.md
|
|
```
|
|
|
|
```
|
|
/build step 5 of the build order — the practice index and all six area pages
|
|
```
|
|
|
|
```
|
|
/build the intake form on /contact/, per docs/05-backend-spec.md.
|
|
Booking stays parked — reserve the slot, render nothing.
|
|
```
|
|
|
|
**When you are making a decision rather than assigning work**, say so plainly and
|
|
let it record the decision:
|
|
|
|
```
|
|
Decision: drop the /for-parties/ page. The plain-language audience can be
|
|
served by a section on /mediation/ instead. Update AGENTS.md and the
|
|
architecture spec, then tell me what else this affects.
|
|
```
|
|
|
|
**When you want an opinion before committing**, ask for one — do not ask for
|
|
code:
|
|
|
|
```
|
|
Before building /fees/: read docs/07-fees.md and tell me what a referring
|
|
lawyer would find missing from that page. Do not write anything yet.
|
|
```
|
|
|
|
## What it will do without being asked
|
|
|
|
- Stop and ask when a task conflicts with a locked decision, or needs a fact it
|
|
does not have. A blocked build is a correct build.
|
|
- Leave `TODO(pouya)` in the source and a numbered question in `AGENTS.md` §9
|
|
rather than inventing a fact or softening a claim into something defensible.
|
|
- Surface `AGENTS.md` §12 Standing Reminders at the start of a substantial
|
|
session — including R1, your standing instruction about the licensure wording.
|
|
- Refuse to publish a claim that is not in the §4 Verified register.
|
|
- Append a Change Log entry covering decisions and plans, not only code.
|
|
|
|
## What to watch for
|
|
|
|
**A review that finds nothing.** Possible, but it should be rare, and it must
|
|
list which lenses were applied and what was checked. "Looks good" is not a
|
|
review — send it back.
|
|
|
|
**Findings declined without a reason.** Declining is legitimate. Declining
|
|
silently is not; the reasoning belongs in the Change Log so a later reader can
|
|
see that judgement was exercised rather than the finding missed.
|
|
|
|
**A check reported as passing that was not run.** "Should pass" is not a result.
|
|
If a build, a Lighthouse run, or a JavaScript-disabled render was not actually
|
|
executed, it must say so.
|