🗂️ Feature Docs

The 7-step flow and its rules

New features (from 2026-10-01) go through seven steps, each approved before the next starts. Steps map onto the four documents above plus four extra files:

Checklists use checkboxes. The Build Plan has a progress list (one - [ ] per subtask) and every subtask's "done when" list is - [ ] items, one concrete check each; QA & Release ends with a readiness checklist the same way. Tick an item (- [x]) in the source file only when it has really landed (merged and tested; for release items, live), then republish. hoop-docs renders them as checkboxes.

Tick the checklist as soon as each task is done — without being reminded. The moment a subtask, a fix or a release step lands: tick its boxes in the same commit as the work, republish the page right away, then report it in the room. A task is not finished until its box is ticked on the live page: ticked in the file but not republished does not count. The same goes for the step status lines, the Changes log and the code-review table.

Decisions made during the steps go into adr/ as usual, one ADR file each (a decision written only inside the PRD does not count). The seven files are published as one page with seven tabs on hoop-docs, plus an ADR tab built from adr/ on every publish; the /features page shows an ADR · N badge per feature that opens it (mddir: in the tabbed_page.py line; @0008-0011 limits it to one phase's ADRs). Add a tabbed_page.py line in tools/deploy_docs.sh and a row in tools/docs_index.py. The blank template, as the same kind of page: feature-template. Example: admin/audit-log.

Tests come first (TDD), except screenshots. In step 5, each subtask starts from the test cases listed in step 6:

1. Backend logic, database, and app behaviour (taps, filters, what gets sent): write the tests first, run them and see them fail, then write the code until they pass.
2. Screenshot (golden) tests: written after the screen exists and checked by eye. A picture cannot be expected before it is drawn.
3. Every test is still shown to fail on a deliberate break of the finished code, then restored (this catches tests that pass for the wrong reason).

If a test written first turns out to disagree with the code you want to write, that is a question for the PRD owner, not a quiet change to the test.

Code is reviewed independently of the session that wrote it. Part of step 5:

1. Before release, the whole build gets one code review against the PRD and Tech Spec: correctness, security, data safety, speed, and whether it does what the PRD asked.
2. Risky subtasks are reviewed as they land, not only at the end: database changes, money / Sparks, login and permissions, anything that deletes.
3. Who reviews: by default the author runs an independent review: a fresh, separate reviewer session that sees only the PRD, the Tech Spec and the diff, not the author's notes or reasoning. The author rereading their own code does not count. A second agent reviews instead only when the requester explicitly asks for one. Before each review, ask the requester once whether they want a second agent; if there is no reply within 15 minutes (or the question is passed over), go ahead with the default.
4. Findings go in the Build Plan's "Code review" section, one line each: fixed (with the commit), or left on purpose (with the reason). Release waits until every finding has one of the two.

Every feature also covers these, inside the step they belong to:

• High-Fi (3): the Chinese version of key screens with the longest real texts, and large system text: nothing cut off.
• Tech Spec (4): Older app versions (what a phone on an old build does after the server changes; never remove or rename a field an old build reads) and Security and privacy (who can see / change it, personal data and how it is masked, how long it is kept, what goes in the Admin Audit Log).
• Build Plan (5): any database change takes its number from the ledger, is dry-run on real production data in a rolled-back transaction, has written undo steps, and is tested twice on sample data. QA & Release (6) checks the counts match on production.
• Changes & Maintenance (7): an After release check about 7 days after release: each PRD goal measured, met or not, and what we watch for errors.

Big changes after release use the same seven steps. Connecting a section, new scope or new behaviour gets a sub-folder (e.g. invite/) with the same seven files and its own seven-tab page. A step with little to say stays short (one mock, a few lines) but keeps its own number and tab: never merge or skip a step, so phases can be compared side by side. Example: admin/audit-log/invite.

Prompt to start a new feature (copy, fill in the [brackets], paste in the work room)

New feature: [Feature name]
Area: [e.g. admin / invite / hoopspark]
What I want: [1–3 sentences: the problem and what the feature should do]

Before writing any code, create the feature documentation first, one step at a time. Wait for my explicit approval of each step before starting the next one. Do not modify or implement any code until all steps up to QA & Release are approved.

Follow our 7-step documentation process:
1) PRD: what the feature should do and why it is needed (problem, goals, non-goals, users, scope, requirements, acceptance criteria, open questions)
2) Wireframe: the user flow, layout and structure (low fidelity)
3) High-Fi UI/UX: the final visual design and user experience (dark and light mode, Chinese version of key screens, large text)
4) Tech Spec: how it will be technically implemented (data, backend, API, app, older app versions, security and privacy, tests)
5) Build Plan (database changes: ledger number, dry run on production data, undo steps): implementation tasks, dependencies, development checklist and execution order (progress list + every checklist item as a checkbox, ticked as each item lands); each subtask writes its behaviour tests first and sees them fail before the code (TDD), screenshots after; the code is reviewed in a separate, independent reviewer session before release (risky parts as they land); before each review, ask me whether I want a second agent instead; if I don't reply, use the default and proceed
6) QA & Release: testing, acceptance, deployment and release readiness
7) Changes & Maintenance: how changes after release are handled, change log, known issues, monitoring, owner, and an after-release check against the PRD goals about 7 days after release

Rules:
- Put the files in docs/features/[area]/[feature-name]/ (prd.md, wireframe.html, high-fi.html, tech-spec.md, build-plan.md, qa-release.md, changes.md, adr/), and add the feature to docs/features/README.md
- Publish it on https://hoop-docs.pages.dev/ as one page with 7 tabs plus an ADR tab, and send me the link after each step
- Check the current code and live data before writing; state facts, not guesses
- End each step with your suggestions for any open questions, then wait for my answers
- Record every decision I make in adr/ (one file each)
- Tick each checklist item as soon as its task is done, in the same commit, and republish the page right away (don't wait to be reminded)
- Use plain English; one language per sentence