← 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.

Other Open Roles

Technischer Redakteur (w/m/d
Tornos Technologies Poland Sp. Z o.o. • Kty Wrocawskie
Technical Writer with English
PerkinElmer Polska Sp. z o.o. • Krakw

Change Your Password

Choose a new password (at least 8 characters, with uppercase, lowercase, a number, and a special character).
Note: changing your password will log you out of all active sessions.