← Back to dashboard
scan 12: technical-writer audits the README, then restructures it
Uphealther • Remote/Nationwide
Login to Apply
Step 12 of 12 in #334. Blocked by #345.
The README is the repository's front door. It takes a stranger from a clean clone to a running
system, and it points to every other document (global CLAUDE.md, Repository baseline).
`technical-writer` carries the README standard of the `readme` skill: grounding in the repository,
the section order, the design rules, and the hard rules. This scan audits the README against that
standard, then fixes what the audit finds.
It runs last because the README routes to every other document, so it is written once they are
final.
## Scope
Record `git rev-parse origin/dev` on this issue when the scan starts. Each dispatch reviews **the
whole of its paths at that commit, not a diff**, and says so: the agent's default scope is the diff
from the merge-base, which would be empty here. A dispatch briefs the agent with its scope and the
documents to check against, never with the findings anyone expects.
`README.md`, checked against the repository it describes. Nothing else changes here: a fix that
belongs in another document is a finding for that document, and step 11 has already checked them.
## How it runs
1. **Inputs.** The standard needs four answers before it can judge the structure: the audience, the
maturity, the deployment target, and the host. Three are known today. The host is GitHub. The
maturity is pre-launch. The target is local through Docker Compose, with AWS planned in #198. The
audience is the owner's call, asked on this issue.
2. **Audit.** In audit mode, which is read-only, the agent ranks findings from blocker to nit. The
report is posted on this issue.
3. **Restructure.** Restructure mode applies the verified findings. Every command the README quotes
is run, and every link and anchor resolves.
## Already tracked
None at the time of filing. Findings are still matched against the open issues while they are
verified.
## Then fix what it finds
1. **Verify.** Every finding is checked against the code at the recorded commit, reproduced where it
can be, and a wrong one is rejected with the reason.
2. **Report.** The verified findings are posted on this issue in the CLAUDE.md finding format
(severity, `file:line`, rule, evidence, failure scenario, fix), followed by the rejected ones and
why each was rejected.
3. **Sort.** A finding an open issue already tracks is linked to that issue, with any new evidence
added there as a comment, and is not fixed here. A finding that needs the owner's decision is
asked on this issue and waits for the answer.
4. **Fix.** Every other verified finding is fixed, whatever its severity:
- on `type/short-kebab-description` branches cut from `dev`, one logical change per commit;
- by the writer agent that owns the change: `implementer` for production code, `test-engineer`
for tests (a bug fix starts with a failing test that reproduces it), `refactoring-engineer` for
behaviour-preserving restructuring, `technical-writer` for Markdown, `code-documentor` for
comments;
- with an ADR when a fix makes a decision, and with `requirements.md` and `architecture.md`
changed in the same commit as the behaviour they describe.
5. **Merge.** Each PR passes the review panel and the root `npm test`, goes into `dev` marked as
part of this issue, and the last one closes it.
## What "done" looks like
- The scan's commit, its verified report and its rejected findings are on this issue.
- Every verified finding is merged, linked to the open issue that tracks it, or settled by the
owner's decision.
- `dev` is green after the last merge.