# Arrancar Unidad

> Start a unit of work the way this project requires - re-analyse the repository as it actually is, look at the running system, ask every question, write the development document, and wait for approval before a single line of code. Use when starting any feature, phase or fix.

- Skill: `uner4s/arrancar-unidad` (Agent Skill)
- Install (CLI): `npx skillmds@latest add uner4s/arrancar-unidad`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uner4s/arrancar-unidad/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Uner4s (https://skillmd.com/u/uner4s)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/uner4s/arrancar-unidad

---


# 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

1. `AGENTS.md` — the standard for this repo.
2. `docs/development/README.md` — the order, the template, and why the questions come first.
3. `docs/development/gotchas.md` — what was already paid for once. Do not rediscover it.
4. The previous unit's document, especially its **`Open`** section. That is where the decision
   you now have to make is usually already named.
5. Whatever the `Detail documents` router in `AGENTS.md` points 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:

```bash
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 when` is 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:

```bash
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.