Uner4s Starting a unit of work
This unit: $ARGUMENTS
docs/development/README.md owns the rule and the template. This is the running order, and
the two steps that get skipped are 3 and 4.
.claude/hooks/documento-aprobado.sh will refuse to let you edit implementation code until the
document says approved. The hook is a backstop, not the reason.
1 · Read, in this order
AGENTS.md— the standard for this repo.docs/development/README.md— the order, the template, and why the questions come first.docs/development/gotchas.md— what was already paid for once. Do not rediscover it.- The previous unit's document, especially its
Opensection. That is where the decision you now have to make is usually already named. - Whatever the
Detail documentsrouter inAGENTS.mdpoints at for what this unit touches.
2 · Register the active unit
Name the document for what it builds, never for a phase number, then arm the gate:
echo "<what-this-builds>.md" > .claude/unidad-activa
From here, implementation edits are blocked until the document exists and is approved. That is intended: it is the same instant at which it becomes tempting to start.
3 · Look at the real system — before writing the document, not after
The most expensive lesson available: a careful, approved document can still need a dozen corrections, and nearly all of them come from touching the running system rather than from re-reading documents.
Answer these against the machine, not against the docs:
- What does the repository actually contain right now — branch, uncommitted work, how far it has drifted from the default branch?
- Do the build, the type check and the test suite pass today?
- What does the data or the running service actually hold, as opposed to what a document says it holds?
- Which of this unit's dependencies exist already, and which are still described in the future tense?
Write down where reality and the documents disagree. That gap is usually where the work is.
4 · Ask. Everything. Then stop.
Every ambiguity, every undecided point, every place where two readings produce different code. Including the ones that turn out not to matter.
Stop here and wait for the answers. Do not write the document with the questions still open, and do not answer them yourself — an assumption written confidently reads exactly like a decision, and that is the failure this whole order exists to prevent.
5 · Write the document
The template is in docs/development/README.md. Status: draft. The Questions asked table
carries the answers from step 4 with their consequence — an answer with no consequence was
not a question worth asking. What was decided elsewhere gets linked, never restated.
It must be complete enough that the implementation is transcription, not invention.
6 · Wait for Status: approved
A human sets that line by hand. Never edit it yourself — the whole point is that the lock and the key are not in the same hand. Ask for the review and wait.
7 · Then code
- Execute this unit only. Do not advance to the next one.
- When reality contradicts the document, fix the document first.
- The unit ends when its
Done whenis demonstrated — not when the code compiles.
8 · On closing
Fill the Result: what actually happened, and how it differed from the plan. Set the
document's Status: done and clear the gate:
rm -f .claude/unidad-activa
If this unit has a counterpart in another repository, it starts now and not before — the contract it depends on is closed first. That is a separate session, in that repo, with its own document.