detail-loop — refine a product unit by unit until review finds nothing new
Once the skeleton works, the difference left is in the details, and a model has more capacity to
spend on them than a person does. The product can be code (a CLI, a library, an API, an app), a web
page, or writing (an article, a README, documentation). This skill spends it: the product's details are split into units
(one rule of the craft each), every fixed detail becomes a check that reruns on every change, and
rounds continue until fresh reviewers find nothing new to adopt. The bar for every round is that
the product holds up to an expert of each field, not that it works.
It runs three phases in turn and owns the order, the interference between units, and when to stop.
Each phase has its steps in a reference. Read it when the phase starts:
${CLAUDE_SKILL_DIR}/references/review.md — finds unfinished details and sorts them into the ledger
${CLAUDE_SKILL_DIR}/references/units.md — folds findings into units in eval/units.yaml (the format's owner)
${CLAUDE_SKILL_DIR}/references/freeze.md — freezes one unit into a check and proves it can fail
The references name other files by their path from ${CLAUDE_SKILL_DIR}, the directory holding
this SKILL.md (references/units.md, scripts/validate_units.py); <skill dir> in a command is
that directory. references/web.md adds the setup for a web product.
Invocation
- No argument: run the loop from step 0.
review, units or freeze <unit-id>: run only that phase's reference on the product in the
working directory, and end with that reference's hand-off or report.
0. Start
- Start when the product's direction is decided and its skeleton builds without errors. Earlier,
details get redone when the structure moves.
- Confirm the version the product ships from (skill:
repair-discipline, when installed and unclear), and work on
a branch of it.
- When
eval/units.yaml exists, run its frozen checks first. Red checks are the first work.
- Find out whether the author delegates the calls (「任せる」「全部あなたの推奨で」). Delegated, the
author's touchpoints are the start and the finished product; follow Delegation below.
- For writing, whether the text gets across to a reader is skill:
persona-read-loop's job when it is installed; this loop
works the craft details.
Delegation
When the author delegates, the loop decides the author calls, the hybrid ranges and the field list
itself and keeps going, so the author meets one finished product instead of a queue of questions.
- Decide in the author's environment. Measure and look where the author meets the product: the
author's OS, runtime, terminal and editor for code, every browser engine the author uses for a page,
the platform and device the author reads on for writing. Delegated calls that were reversed came from judging
in a different engine than the author's, not from deciding without asking.
- Decide, freeze, continue. Record each decision in
decided_by with the author's delegation
words, and freeze it like any other unit.
- The author's own words and publishing stay with the author. Copy the author wrote or will sign,
and any outward action (push, deploy, post), wait for the author even under delegation. In writing,
the loop changes how the text is shown (markup, notation, terms as the author's glossary sets them,
links, code blocks, figures); a change to the wording or a claim goes back to the author as a
proposed edit (
author call).
- A later reversal by the author is one more ledger line, worked like any adopted finding.
1. Round
- Run the review phase (
references/review.md) on the current build.
- Run the units phase (
references/units.md) with the adopted findings. On the first round the author approves the
field list (⏸); later rounds add to it.
- Work the units one at a time (step 2).
- Start the next round. It works the
machine units while hybrid ranges and author call lines
wait for the author's answers (under delegation, those are already decided). The hand-off (step 5)
comes at done or stuck (step 4).
2. One unit
- Pick the next unit: units with failing instances first, then by how visible the failure is to a
reader.
- Change the cause named in the unit, and nothing else. Scope the change to the instances the finding
names (its language, platform, command, page): a rule written for English titles reached Japanese
lines, and a tie chosen for one font drew a double space in another; the next round found both as
regressions.
- Freeze an
open unit with the freeze phase (references/freeze.md). Change a frozen unit's
expectation only through references/units.md, Changing an expectation. author units are listed for the author.
- Run every frozen check. A unit that moved without being touched has a relation: record it in
relations (references/units.md).
- Record the ledger lines and commits the freeze phase writes (the fix, then the freeze).
3. Interference
When fixing one unit breaks another, look for a cause that satisfies both before trading one away
(two units often draw on one shared budget — width, time, memory, a sentence's length; on a web
page the Japanese size and a line break after a phrase both needed the column width, and lowering
the English size satisfied both). A fix often meets a third unit on the way, so run every frozen check
after each attempt; the second fix is where the third unit shows up. When none exists, the priority is the author's call: hand over both
units, the measured values, and the options.
4. Done and stuck
Done needs all three:
- every frozen check is green, no
machine unit is open, and every hybrid unit with
decided_by is frozen (the validator's counts)
- the latest review round found nothing new to adopt (no new unit and no new instance of an
existing one), and the author has read that round's
not adopted lines with their reasons (the loop decides adoption, so the author checks it)
- the author has answered the
hybrid ranges and author call lines, and has read the
author-eye units and the round's screenshots or captured output in the author's environment. Under delegation the
loop has decided these; the author's read of the finished product closes it
All checks green alone is not done: the checks hold what was found, and only review finds more.
Stop and hand to the author when:
- the same two units have flipped each other twice (an interference with no shared fix)
- a unit's expectation could not be written as one check after two tries — propose making it an
author unit; the author decides
- a unit's ledger lines show more expectation changes than detections — propose retiring the unit
- the session's time or token budget is spent
5. Hand to the author
- The ledger lines added this session, with the
not adopted lines and their reasons, and the commits
- The units by judge and status (the validator's counts), and what changed since the start
- The
hybrid units waiting for a range, with the measured values
- The
author-eye units and the screenshots or captured output to read
- Under delegation: the finished product, and the decisions made for the author that change how it
looks, reads or behaves most, each with a screenshot or captured output in the author's environment
and a one-line way back.
The rest stay in the ledger
- The stop reason, in one line
1---2name: detail-loop3description: "God is in the details: take a product whose skeleton is done and refine it unit by unit, freezing each fixed detail as a check, until a review round finds nothing new."4disable-model-invocation: true5user-invocable: true6argument-hint: "[review | units | freeze <unit-id>]"7origin: shimo42288metadata:9 source: https://skillmd.com/skills/shimo4228/detail-loop10---1112# detail-loop — refine a product unit by unit until review finds nothing new1314Once the skeleton works, the difference left is in the details, and a model has more capacity to15spend on them than a person does. The product can be code (a CLI, a library, an API, an app), a web16page, or writing (an article, a README, documentation). This skill spends it: the product's details are split into units17(one rule of the craft each), every fixed detail becomes a check that reruns on every change, and18rounds continue until fresh reviewers find nothing new to adopt. The bar for every round is that19the product holds up to an expert of each field, not that it works.2021It runs three phases in turn and owns the order, the interference between units, and when to stop.22Each phase has its steps in a reference. Read it when the phase starts:2324- `${CLAUDE_SKILL_DIR}/references/review.md` — finds unfinished details and sorts them into the ledger25- `${CLAUDE_SKILL_DIR}/references/units.md` — folds findings into units in `eval/units.yaml` (the format's owner)26- `${CLAUDE_SKILL_DIR}/references/freeze.md` — freezes one unit into a check and proves it can fail2728The references name other files by their path from `${CLAUDE_SKILL_DIR}`, the directory holding29this SKILL.md (`references/units.md`, `scripts/validate_units.py`); `<skill dir>` in a command is30that directory. `references/web.md` adds the setup for a web product.3132## Invocation3334- No argument: run the loop from step 0.35- `review`, `units` or `freeze <unit-id>`: run only that phase's reference on the product in the36 working directory, and end with that reference's hand-off or report.3738## 0. Start3940- Start when the product's direction is decided and its skeleton builds without errors. Earlier,41 details get redone when the structure moves.42- Confirm the version the product ships from (skill: `repair-discipline`, when installed and unclear), and work on43 a branch of it.44- When `eval/units.yaml` exists, run its frozen checks first. Red checks are the first work.45- Find out whether the author delegates the calls (「任せる」「全部あなたの推奨で」). Delegated, the46 author's touchpoints are the start and the finished product; follow Delegation below.47- For writing, whether the text gets across to a reader is skill: `persona-read-loop`'s job when it is installed; this loop48 works the craft details.4950## Delegation5152When the author delegates, the loop decides the author calls, the `hybrid` ranges and the field list53itself and keeps going, so the author meets one finished product instead of a queue of questions.5455- **Decide in the author's environment.** Measure and look where the author meets the product: the56 author's OS, runtime, terminal and editor for code, every browser engine the author uses for a page,57 the platform and device the author reads on for writing. Delegated calls that were reversed came from judging58 in a different engine than the author's, not from deciding without asking.59- **Decide, freeze, continue.** Record each decision in `decided_by` with the author's delegation60 words, and freeze it like any other unit.61- **The author's own words and publishing stay with the author.** Copy the author wrote or will sign,62 and any outward action (push, deploy, post), wait for the author even under delegation. In writing,63 the loop changes how the text is shown (markup, notation, terms as the author's glossary sets them,64 links, code blocks, figures); a change to the wording or a claim goes back to the author as a65 proposed edit (`author call`).66- **A later reversal by the author is one more ledger line**, worked like any adopted finding.6768## 1. Round69701. Run the review phase (`references/review.md`) on the current build.712. Run the units phase (`references/units.md`) with the adopted findings. On the first round the author approves the72 field list (⏸); later rounds add to it.733. Work the units one at a time (step 2).744. Start the next round. It works the `machine` units while `hybrid` ranges and `author call` lines75 wait for the author's answers (under delegation, those are already decided). The hand-off (step 5)76 comes at done or stuck (step 4).7778## 2. One unit79801. Pick the next unit: units with failing instances first, then by how visible the failure is to a81 reader.822. Change the cause named in the unit, and nothing else. Scope the change to the instances the finding83 names (its language, platform, command, page): a rule written for English titles reached Japanese84 lines, and a tie chosen for one font drew a double space in another; the next round found both as85 regressions.863. Freeze an `open` unit with the freeze phase (`references/freeze.md`). Change a frozen unit's87 expectation only through `references/units.md`, Changing an expectation. `author` units are listed for the author.884. Run every frozen check. A unit that moved without being touched has a relation: record it in89 `relations` (`references/units.md`).905. Record the ledger lines and commits the freeze phase writes (the fix, then the freeze).9192## 3. Interference9394When fixing one unit breaks another, look for a cause that satisfies both before trading one away95(two units often draw on one shared budget — width, time, memory, a sentence's length; on a web96page the Japanese size and a line break after a phrase both needed the column width, and lowering97the English size satisfied both). A fix often meets a third unit on the way, so run every frozen check98after each attempt; the second fix is where the third unit shows up. When none exists, the priority is the author's call: hand over both99units, the measured values, and the options.100101## 4. Done and stuck102103Done needs all three:104105- every frozen check is green, no `machine` unit is `open`, and every `hybrid` unit with106 `decided_by` is `frozen` (the validator's counts)107- the latest review round found nothing new to adopt (no new unit and no new instance of an108 existing one), and the author has read that round's109 `not adopted` lines with their reasons (the loop decides adoption, so the author checks it)110- the author has answered the `hybrid` ranges and `author call` lines, and has read the111 `author-eye` units and the round's screenshots or captured output in the author's environment. Under delegation the112 loop has decided these; the author's read of the finished product closes it113114All checks green alone is not done: the checks hold what was found, and only review finds more.115116Stop and hand to the author when:117118- the same two units have flipped each other twice (an interference with no shared fix)119- a unit's expectation could not be written as one check after two tries — propose making it an120 `author` unit; the author decides121- a unit's ledger lines show more expectation changes than detections — propose retiring the unit122- the session's time or token budget is spent123124## 5. Hand to the author125126- The ledger lines added this session, with the `not adopted` lines and their reasons, and the commits127- The units by judge and status (the validator's counts), and what changed since the start128- The `hybrid` units waiting for a range, with the measured values129- The `author-eye` units and the screenshots or captured output to read130- Under delegation: the finished product, and the decisions made for the author that change how it131 looks, reads or behaves most, each with a screenshot or captured output in the author's environment132 and a one-line way back.133 The rest stay in the ledger134- The stop reason, in one line