ll-skills 1.0.0 → 2.0.2

package/skills/ll-brainstorm/references/decision-policy.md

@@ -0,0 +1,118 @@
+# Decision policy
+
+Shared by `ll-brainstorm`, `ll-decide` and `ll-implement` (three byte-identical copies; master in
+`skills/ll-brainstorm/references/`).
+
+## The three bands
+
+### Band 1 — ask, never decide alone
+- Real money above the ceiling of the round. A cost question dismissed without an answer is not a delegation.
+- Irreversible outside the repo: push that deploys, merge to a protected main, `terraform apply`
+  with destroys, a credential created or copied to a new place, a write to a production database,
+  a load of personal data.
+- Price, packaging, a promise to a customer.
+- Scope cut of the round — keep the maximalist option on the table.
+- The number the owner will look at on screen: denominator, window, what counts as an event.
+- A recorded rule contradicted by new evidence (asked first, alone); waiving "partial is failure".
+- A reference the owner cites that the session cannot open (prototype, document, link, artifact):
+  ask him to attach or paste it. Its content is never assumed.
+In autonomous runs: freeze only that branch, record `WAITING`, continue what does not depend on
+it. Waiting is not authorization.
+
+### Band 2 — decide, record, continue
+- Reversible technical detail inside a closed contract — decided now, changed later if needed.
+- A house pattern exists (infra, CI/CD, names, repo layout) — follow it.
+- Who executes: agent vs session, worktrees, model per wave.
+- A fact readable from the repo, the database or the infrastructure — look it up.
+- A subject outside the round's scope.
+- Confirmation of what another session already decided with the owner.
+- Copy without a commercial promise — blind judge, not a question.
+Recorded as `DEC-` with an id reserved by the session; executors return `BLOCKED: <decision>`
+instead of creating one. In an opening conversation these are the A items.
+
+### Band 3 — decide, execute, flag for review
+- Overrun inside the agreed tolerance; above it, stop and diagnose.
+- Copy or style with an independent blind opinion attached.
+- A constraint invented out of caution that restricts the product (masking data, hiding a number,
+  limiting access) — "I masked X; review, reversible", never an invariant.
+- A choice whose revert costs ≤ 1 commit. All marked `[revisable]` with a `Review trigger:`.
+
+### Blanket delegation
+"Pode decidir tudo, me pergunta só o que for realmente necessário" delegates bands 2 and 3, never band 1:
+band-1 items are still asked, in one block of ≤4 with the recommendation marked. Zero questions plus a stack of assumptions has misread it.
+
+## Contact minimum
+Every planning skill (`ll-brainstorm`, `ll-decide`, the phase conversation of `ll-implement`) ends
+with a final round that shows `questions asked N / assumptions M / band-1 open K`, even when N = 0.
+Silence of 10 minutes ratifies the recommended list (A), never a blocking item (B).
+
+## Never ask (10 items)
+1. Who executes — agent vs session, worktrees, model per wave. Decide it and record it.
+2. A fact readable from the repo, the database or the infra — look it up, including whether it was already done.
+3. Which pattern, when a house pattern exists — follow it.
+4. A reversible technical detail inside a closed contract — decide it now, change it later if needed.
+5. Confirmation of what another session already decided with the owner — ceremonial, it only gets confirmed.
+6. A subject outside the round's scope, however related it looks.
+7. A question whose answer changes no action — asking it stalls whatever is running.
+8. Copy without impact on a commercial promise. Route it to a blind judge instead.
+9. Industry defaults — data retention, performance target, error format, default auth. Recorded in Locked with backing.
+10. The same policy question a second time, however it is rephrased.
+
+## Silence, delegation, directives
+- Silence for 10 minutes in the hot window (harness AFK timeout) ratifies option A of a band-2/3 item or
+  list A of a map — never option B, never a band-1 item. Record `ratified by silence`; in a run, `[decided by absence — revisable]`.
+- "Claude decide", "você decide", "pergunta pro time" are legitimate answers: record an assumption
+  `ASM-n` (permanent; announced if changed later) or the delegation, and never ask that item again.
+- An order against the recommendation is a directive: one challenge with the cost named, then
+  obey; record it under "Against the recommendation — do NOT re-litigate".
+- Settled (the owner decided, or ratified) is never re-opened; cite the ID when it resurfaces. Only the
+  owner's ratification settles an item. When he corrects a premise in free text ("na verdade…",
+  "validei com o time e…"), write the dated decision and a `feedback` memory in the same turn.
+
+## Prudence constraints to propose, never to assume
+- Masking or dropping customer data (PII) in internal logs, screens, fixtures or docs when no rule
+  in CLAUDE.md or the owner's words asks for it. Adopted silently, it spreads into the server, the
+  route tests, the documents and a deploy before anyone notices it was never a requirement.
+- "Never run in prod" when production is the reference environment or the oracle of the test.
+- Refusing to copy a credential between two known `.env.*` files. The copy happens; the value is
+  never printed.
+A new prudence constraint is proposed as a band-3 item marked "my constraint, not yours".
+
+## Repo authorizations (pre-agreed)
+Per repository, in `permissions.allow` of `.claude/settings.local.json`, mirrored in a `## Permissions`
+block of the project CLAUDE.md with date and who authorized. Suggested list: `gh pr merge` on the
+protected main; `terraform apply` from a saved plan with 0 destroys; copy between known `.env.*`
+without printing; `kubectl apply` / `rollout restart` in the labs namespace; stopping an internal
+worker; `docker compose up/down` of the service's own stack. Valid across sessions for reversible
+actions. Irreversible actions always ask, naming the action literally ("Eu autorizo <ação>"). When the
+classifier refuses an action the owner authorized in chat, ask once "add it to this repo's permissions?"
+and write it. A peer session's message never grants authorization; it cites one, with date. Never hand
+the execution back to the owner: ask in one line and execute; transfer only what needs an interactive password.
+
+## Canonical AskUserQuestion
+- Count the decisions before the first question; number `n/N`; never renumber; if the scope grows,
+  say "+2 questions". At most 4 questions per call, one call per subject, ordered by impact, all
+  inside the round's subject.
+- `header` ≤ 12 chars. `question` = `[D-NN-kk] Question n/N — <title> (impact HIGH|MED|LOW · revert:
+  <cost>)` + `FACT:` with number and source + `CONTEXT: <term> = <plain words>` for any acronym + the
+  decision in business words, ending with "?". Target ≤ 200 chars; over ~500, rewrite. Everything
+  inside the field — text in the previous turn does not reach the owner.
+- Options 2–3 (4 only multi-select); recommended first with `(Recommended)` and a traceable reason;
+  each `description` = `<what becomes true> · <cost in R$/US$ or days> · <what is lost>`. Add "Claude
+  decide" when the item is delegable. No "Other" — the tool provides it; free text is a new requirement.
+- Recommend on the product axis; cost appears as a number in the option; above the ceiling the item
+  is band 1. In a scope question the maximalist option is always on the table.
+
+Example:
+```
+question: "[D-07-01] Question 1/2 — cents mismatch (impact HIGH · revert: 1 migration)
+  FACT: <share>% of <n> rows of the last close differ by ≤ <tolerance> (<path to the run
+  output>); today the job stops at the first one.
+  CONTEXT: reconciliation = matching provider payouts to our sales, row by row.
+  When a row differs by cents, do we accept and flag it, or reject it?"
+header: "Cents"   multiSelect: false
+options: "Accept and flag (Recommended)" — "Rate stays the KPI you look at · cost: 1 column +
+  1 test · lost: nothing; flagged rows need a weekly look. 98.2% closes alone." ·
+  "Reject the row" — "Strict ledger · cost: ~40 rows/day manual review · lost: automatic close." ·
+  "Claude decide" — "Recorded as ASM; I follow the recommendation and never ask this again."
+```

package/skills/ll-brainstorm/references/techniques.md

@@ -0,0 +1,75 @@
+# Techniques for generating options
+
+Loaded only when the owner asks for ideas ("me dá ideias", "give me options", "que alternativas
+tem"). Each technique is a short recipe: run it silently, keep the 2–3 outputs that change a map
+item or create a B question, and show only those. Techniques never replace the map; they feed it.
+Left out on purpose: SCAMPER, Six Hats, Disney rooms and the theatrical catalogues — too much
+ceremony for a phase that already has a scope.
+
+## Finding the invented rule
+
+**Assumption reversal** — when an A item feels like caution rather than a requirement.
+List every assumption baked into the phase, flip each to its opposite, rebuild the design on the
+inverted set. Any assumption whose flip costs nothing was a rule you invented: mark it
+`[revisable — my constraint, not yours]`. This is the technique that catches a prudence rule the
+plan adopted on its own, before it spreads into code, tests and documents.
+
+**Constraint mapping** — when the phase looks over-constrained.
+Write every constraint; sort each into "business" (band 1, the owner's) or "self-imposed"
+(band 3, yours). Attack each self-imposed one: dissolve it, route around it, or turn it into a
+feature. Business constraints go to PREMISES; self-imposed ones go to A as revisable.
+
+## Finding the B questions
+
+**What would have to be true** — when unsure which points need the owner.
+List what has to hold for the phase to succeed; grade each statement by importance × evidence.
+High importance + weak evidence = a B question; high importance + strong evidence = an A item
+with the evidence as backing; low importance = C.
+
+**Job to be done** — when the owner describes a feature, not an outcome.
+Ask what he is hiring this phase to do and what he will look at on screen when it is done. The
+answer is the number that decides success — the one axis he never delegates. Ask it once, in B.
+
+**Question storming** — the default way to build the internal queue.
+Generate only questions about the phase, zero answers, until the real problem comes into focus.
+Then classify each question Mechanical / Taste / Blocking. The list is never shown whole.
+
+## Generating alternatives
+
+**Morphological analysis** — when one design is on the table and the owner wants options.
+List the phase's independent parameters (storage, trigger, retry, reporting…), 2–3 options for
+each, combine across them into 2–3 coherent approaches. Present each with cost and what is lost;
+recommend one with a reason from the repo.
+
+**Analog from another domain** — when the repo has no analog for an item.
+Ask "this is like what?" — a queue, a ledger, a cache, a checkout. Take the solution pattern from
+the domain that answers and name it in the item (`[no analog in repo — pattern: idempotent
+ledger]`). The in-repo analog at `file:line` still wins whenever it exists.
+
+**TRIZ contradiction** — when two A items pull against each other.
+Name the contradiction (what only improves by making something else worse), then look for the
+option that wins both before accepting a trade-off. If none exists, the trade-off is a B question.
+
+## Pressure and cut
+
+**"What makes this fail on day 1"** — before locking a high-impact item.
+Assume the phase shipped and broke in its first hour. Name the three most likely causes with the
+signal that would show each. Each cause becomes a test in the phase plan or an accepted risk.
+A full premortem belongs to `ll-decide project` (step 2), as the next command.
+
+**PMI (plus / minus / interesting)** — when one strong candidate needs a last check.
+Three lines: what improves, what gets worse, what is unexpected. If a minus is band 1, the item
+moves from A to B.
+
+**One feature only / ship in 60 minutes** — for scope questions.
+"You keep exactly one capability" and "you launch in one hour with what is on hand — name what
+you cut, fake or borrow." An owner asked to cut usually cuts deeper than the recommendation, so
+offer the cut as an option with the maximalist option next to it.
+
+**Backcasting** — when success criteria are vague.
+Describe the finished phase in observable terms (the screen, the number, the command that proves
+it), then walk backward to the first move. The observable terms become the ROADMAP criteria.
+
+**Impact–effort ranking** — to order B.
+Place each Blocking item on impact × effort; ask the high-impact ones first, `n/N` numbered.
+Two convergence moves chained is enough; more is over-processing.

package/skills/ll-close/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ll-close
+description: Closes a delivery or a milestone — reconciles the backlog against executable conditions, writes docs/DELIVERY.md for the manager, stamps the epilogue with phase-stats, produces a retrospective, promotes the lessons that became permanent rules to project memory and CLAUDE.md, and asks for one block of ratification. Use when the request is "fecha", "fecha a fase", "pode arquivar", "encerra isso", "fecha o milestone", or at the end of a /goal; `--milestone` archives the phases, collapses the ROADMAP and updates the project's current state. It refuses to close without an approved VERIFICATION.md; for the verification itself use ll-verify.
+argument-hint: "[--milestone <name>]"
+disable-model-invocation: true
+allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/ll-tools.js *)
+---
+
+# Close
+
+Current state: !`${CLAUDE_SKILL_DIR}/scripts/ll-tools.js state`
+
+Closing means the next session — or the next person — can pick this up from files alone: what changed and for whom, what was proven and by which command, what stayed open and under what condition it reopens. Nothing is closed from memory: an item closes because its condition ran and passed.
+
+Reply to the owner in Portuguese; every file you write is in English.
+
+## Deliverables
+
+| File | Role | Mutability |
+|---|---|---|
+| `docs/DELIVERY.md` | the eight sections a manager reads, per delivery | one per delivery; `docs/history/` keeps the old ones |
+| `docs/RETROSPECTIVE-<date>.md` | ~60 lines: numbers, cost, permanent rules, what to stop doing | one per large delivery; the only doc the next milestone reads |
+| `PROGRESS.md` | `## Epilogue` with the board, what is left, what waits on the owner, next command | append-only |
+| `BACKLOG.md` | reconciled; new items with an executable condition and their birth phase | closed only by `backlog-reconcile --run` |
+| `CLAUDE.md` (project) | `## Current state`, plus a line per rule that became permanent | short and alive; never a changelog |
+| `docs/history/<milestone>/` | archived phases (`--milestone` only) | write once |
+
+## Gate
+
+Read the verification for the target: the newest by mtime between `phases/NN/VERIFICATION.md` (phase) and `VERIFICATION.md` at the repo root (delivery); say which one opened the gate. Close only on `APPROVED`, or on `APPROVED_WITH_RESERVATIONS` whose reservations are accepted in a `decisions/DEC-*.md` naming them. Anything else — `REJECTED`, `product: FAIL`, `process: FAIL` with no DEC, no verification file at all — stops here:
+
+> Não fecho: `<motivo em uma linha>`. ▶ Next — `/clear`, then `ll-verify NN` (or record the reservations in a DEC and run `ll-close` again).
+
+A verification whose ledger has `STALE` lines is verification of code that moved: it does not open the gate.
+
+## Flow — delivery (default)
+
+1. **Reconcile.** `ll-tools.js backlog-reconcile --run`. Items whose condition passed close; the rest stay open with their exit code. Then add the items born in this delivery — deviations, stubs, tests not run, debt, domain questions — one row each with the next free `B-nnn`, an executable closing condition (`` `<command>` exit 0 ``), state `OPEN`, and its birth phase and commit. An item without a condition is a wish, not a backlog entry.
+2. **Write `docs/DELIVERY.md`** in the eight sections of `references/delivery.md`. The verification section carries the commands, their last output lines and the screenshots that were opened; a claim with no command behind it goes to the assumptions section instead.
+3. **Stamp the epilogue.** `ll-tools.js epilogue <phase> --json` gives passed, left with why, WAITING, new backlog, dirty tree, HEAD and the next command; `ll-tools.js phase-stats --since <YYYY-MM-DD of the phase's first commit>` (a date, not a sha) gives days with work, span, idle days, commits by type and the test/feat ratio. The helper prints the data; the prose around it is yours, in `## Epilogue` at the end of PROGRESS.
+4. **Write `docs/RETROSPECTIVE-<date>.md`** from `references/retrospective.md` — about 60 lines, driven by the numbers from step 3, one lesson per line with the evidence that produced it.
+5. **Promote what is permanent.** A lesson that changes how the next phase runs goes to project memory; a lesson that is a standing rule of this repository goes as one line into the project's `CLAUDE.md`, in the owner's words when he gave them. Two lines at most per delivery: a CLAUDE.md that grows every close stops being read.
+6. **Peer notice.** If a peer session (infra, ops, another repo) shipped, waits on something, or was asked for something in `docs/REQUESTS.md`, that goes in the summary as one line with the request id and its state — not as a new message.
+7. **One block of ratification.** A single `AskUserQuestion`, at most 4 items, only after everything is written: the open pendings with their conditions, and the accepted risks the delivery carries. Options carry the cost of each path and the recommendation is marked. Silence keeps what is written; nothing here blocks the close.
+8. **Report.** Verdict and seals, what changed in one line, numbers from `phase-stats`, open pendings by id, accepted risks, next command.
+
+## Flow — `--milestone <name>`
+
+The list always goes out; the audit ritual is optional and offered once, never imposed.
+
+1. Gate again over every phase of the milestone: any phase with no approved verification is named in the report and its phase directory is archived unclosed, marked as such.
+2. `git mv phases/* docs/history/<milestone>/` — the directories move, they are not deleted. `PROGRESS.md` above its 200-line ceiling collapses into `docs/history/<milestone>/PROGRESS.md`, leaving the current board and the epilogue.
+3. Collapse the closed phases in `ROADMAP.md` into one `<details>` block per phase, keeping the numbering intact — phase 7 stays phase 7 forever, and a later reference to it still resolves.
+4. Transport only what survives: an open pending with an executable condition goes to `BACKLOG.md`; a criterion never proven goes to the next milestone's ROADMAP as a criterion, not as a note. What survives neither test is dropped, and the report says which.
+5. Update `## Current state` in the project's `CLAUDE.md`: what exists now, what the next milestone is, where the history went. Replace the section; do not append to it.
+6. One block of ratification, as in the delivery flow, plus the open pendings the milestone inherits.
+
+## Completion criterion
+
+`DELIVERY.md` and the retrospective on disk, epilogue stamped, backlog reconciled with every open item carrying a runnable condition, memory and `CLAUDE.md` updated, one ratification asked. `--milestone` adds: `phases/` archived, ROADMAP collapsed with numbering intact, `## Current state` current.
+
+- more phases in the ROADMAP → `▶ Next — /clear, then ll-implement <N+1>`
+- last phase of the milestone → `▶ Next — /clear, then ll-close --milestone <name>`
+- milestone closed → `▶ Next — /clear, then ll-decide project` for the next one
+
+## References
+
+`references/delivery.md` — the eight sections of `docs/DELIVERY.md` and the rule for each.
+`references/retrospective.md` — the retrospective template and what each section is allowed to contain.

package/skills/ll-close/references/delivery.md

@@ -0,0 +1,75 @@
+# docs/DELIVERY.md — the eight sections
+
+The format the owner asks for by pointing at an exemplar. Its reader is a manager who did not watch
+the work: he wants to know what changed for him, what was proven, and what he is being asked to
+accept. Eight sections, in this order, no others. A section with nothing in it says so in one line
+and stays — an absent section reads as an oversight.
+
+Ledger, table and prose rules: every claim about behaviour names the command or the `file:line`
+behind it. What was not run goes to §5 as an assumption, never to §4 as a result.
+
+```markdown
+# DELIVERY — <phase NN | round N | milestone name> — <YYYY-MM-DD>
+verification: <path to VERIFICATION.md> · verdict <APPROVED|APPROVED_WITH_RESERVATIONS> ·
+product <OK|FAIL> · process <OK|FAIL> · slice <branch> <sha..sha>
+
+## 1. What changed, for the manager
+<3 to 8 lines, no jargon: what a person can now do that they could not before, where, and from
+when. Numbers where the change is numeric (before and after, in the same unit). No file names
+here — this section survives being pasted into a message.>
+
+## 2. Findings → done
+| # | finding (as reported) | what was done | evidence |
+|---|---|---|---|
+| F-03 | "<the finding, in the words it was reported in>" | <what was done> | `npm test -- <feature>.test.ts` exit 0 |
+<One row per finding that entered this round, including the ones deliberately left out — those get
+"not done, see §6" in the third column. The finding is quoted as it was reported, in the words used.>
+
+## 3. New rules, with an example
+<Rules this delivery makes permanent: an invariant, a naming convention, a forbidden command, an
+access recipe. One line per rule, each followed by one concrete example of the rule applied — a
+rule with no example is not yet a rule. These are the same lines that go to CLAUDE.md in step 5.>
+
+## 4. Verification
+| criterion | command | exit | last output line |
+|---|---|---|---|
+| SC-01 | `npm test -- reconcile.test.ts` | 0 | `Tests: 3 passed, 3 total` |
+<Plus the screenshots that were opened, by path, with what each one shows in a few words: an image
+not opened is a check not done. Commands that were not run appear here with `not run` and the
+reason, never omitted.>
+
+## 5. Assumptions to ratify
+<What was decided on the owner's behalf while he was not there, one per line: the assumption, the
+DEC that records it, what breaks if it is wrong, and how expensive it is to reverse. This section
+feeds the ratification block; if it is empty, say "none — every decision in this delivery is in
+decisions/".>
+
+## 6. Out of this round, and why
+<What was asked for or found and deliberately not done. One line each: what, why (cost, risk,
+depends on an open decision), and the BACKLOG id or the phase where it will be picked up. "Out of
+scope" with no id is how work disappears.>
+
+## 7. Deploy risks
+<Only what is real for this delivery: migrations that are hard to reverse, new environment
+variables, jobs added or renamed, rate limits, data written on first run, order of deploy between
+repos, what to watch in the first hour and where. Each risk names its rollback, or says there is
+none. If the push is the deploy, that sentence appears here explicitly.>
+
+## 8. File inventory
+| path | what it does | new / changed |
+|---|---|---|
+| `src/billing/reconcile.ts` | idempotent reconciliation by (provider, event_id) | new |
+<Every path the delivery touched, grouped by area, from `git diff --stat <range>`. Generated files
+and lockfiles are one line, not one row each.>
+```
+
+## Rules per section, in short
+
+1. **What changed** — the manager's language; no file names; numbers where there are numbers.
+2. **Findings → done** — the finding quoted as reported; one row each, including the refused ones.
+3. **New rules** — one rule, one example; these become the CLAUDE.md lines.
+4. **Verification** — commands, exit codes, last lines, screenshots seen; `not run` stays visible.
+5. **Assumptions** — what was decided for him, with the cost of being wrong.
+6. **Out of this round** — with a reason and an id.
+7. **Deploy risks** — each with its rollback, or an explicit "none".
+8. **Inventory** — everything touched, from the diff, not from memory.

package/skills/ll-close/references/retrospective.md

@@ -0,0 +1,48 @@
+# docs/RETROSPECTIVE-<date>.md
+
+About 60 lines. It is the only document the next milestone is expected to read, so it holds what
+changes behaviour next time and nothing else: no narrative of the phase, no praise, no repetition
+of what `DELIVERY.md` already says. One lesson per line, each with the evidence that produced it —
+a sha, a `file:line`, a number from `phase-stats`, a quoted turn. A lesson with no evidence is an
+opinion and stays out.
+
+```markdown
+# RETROSPECTIVE — <phase NN | milestone> — <YYYY-MM-DD>
+
+## What the numbers say
+<From `ll-tools.js phase-stats --since <YYYY-MM-DD>`: days with work vs. span vs. idle days; commits by
+type; test/feat ratio; milestones passed on the first verification vs. after gaps. 5-8 lines, each
+a number and what it implies. An idle span is data about the process, not a reproach.>
+
+## What cost prompts
+<Where the owner had to intervene, and why: a question that should have been decided by rule, a
+status he had to ask for, a correction of course, a re-run he paid for twice. Cite the turn or the
+command. This is the section that shrinks the next phase — it is written even when the delivery
+went well.>
+
+## Rules that became permanent
+<Each line: the rule, the incident that created it, and where it now lives (project CLAUDE.md,
+PLAN §invariants, an access recipe in PROGRESS). Only rules that are written somewhere by the end
+of this close; a rule that exists only here will not survive.>
+
+## What to stop doing
+<Practices this delivery proved expensive: a command that lies, a parallelism that collided on an
+exclusive resource, a verification that never fires, a document nobody read. Name it and name the
+cheaper replacement. Without a replacement it is a complaint, not a lesson.>
+
+## Lessons
+<One per line, ordered by how much they change the next phase, at most 10:
+- <lesson in one sentence> — evidence: <sha | file:line | number | quoted turn>
+Lessons that generalise beyond this repository are marked `[general]`; those go to memory. The
+rest stay local and are read by whoever plans the next phase.>
+
+## Cost and deferred
+<What the delivery cost where it is measurable (agent runs, wall-clock days, tokens of scaffolding,
+paid API calls) and what stayed open: BACKLOG ids, criteria deferred with their resume command,
+decisions still WAITING. This section is the handoff — the next milestone starts from it.>
+```
+
+Writing rules: past tense, one subject per line, no adjectives of intensity. Never attribute to the
+owner a decision he did not take. Quote his words verbatim where they are the lesson. If a section
+has nothing, write `none this round` and keep the heading — the empty section is itself a finding
+when it repeats.

package/skills/ll-decide/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: ll-decide
+description: Turns a request into a contract that survives without the owner — project mode runs a five-question premise gate, a "back from the future" premortem with clean-context narrators, a disarm pass, a decision room (docs/decide/OPTIONS.html) and an interview in batteries, then writes PLAN.md §0–§11, ROADMAP.md, decisions/ and an empty PROGRESS.md; feedback mode ingests external material (docx/pdf/xlsx/images) forensically, anchors every item in the code, checks its claims, triages by impact, arbitrates competing copy blind and writes docs/review-<date>.md plus the team's .xlsx. Use when the request is "escreva o plano", "vamos desenhar", "segunda tentativa", a new folder, a LARGE-regime request, or in English "write the plan", "let's design it" (project); or pasted .docx/.pdf/.xlsx/image paths with "analise a revisão", "processa o feedback", "vê o que o time sugeriu", "process the review" (feedback). For an open-ended idea start with `ll-brainstorm`; for research first, `ll-research`.
+argument-hint: "[project | feedback] [--measure]"
+---
+
+# Decide
+
+Everything that would otherwise be asked during execution is decided here, once, and written where an agent with a cleared context finds it. The result is judged by one test: a session that has never seen this conversation reads the files and starts implementing without a question. Nothing is implemented here.
+
+Reply to the owner in Portuguese; every file you write is in English.
+
+## Deliverables
+
+Every path is relative to the repo root and fixed: `PLAN.md`, `ROADMAP.md`, `PROGRESS.md`, `BACKLOG.md`, `decisions/`, `docs/decide/`, `phases/NN/`. State never lives in a subfolder — the hooks and `ll-tools.js state` expect the state at the git top, and a displaced tree is reported as `git_top ≠ root` and stops `ll-implement` before its first step, so a `docs/<project>/PLAN.md` costs a move before anything runs. When the root is already taken by a previous round, archive it (step 0); never write the new set beside it.
+
+Never written here: `phases/NN/PLAN.md` — the phase plan belongs to `ll-implement`.
+
+| File | Role | Mutability |
+|---|---|---|
+| `PLAN.md` | project contract, §0–§11 | immutable after freezing except `## Errata` (append-only) |
+| `ROADMAP.md` | phase table + `## Phase NN` with success criteria; written only when the project has more than 3 phases | live; continuous numbering, decimals for insertions, never renumbered |
+| `decisions/DEC-NNNN-<slug>.md` + `decisions/README.md` | one decision per file; index with counts, against-recommendation, verbatim free answers, accepted risks | append-only; IDs never recycled; supersession by a new line |
+| `PROGRESS.md` | empty diary with the `<!-- ll-state -->` block | created here, written by `ll-implement` |
+| `docs/decide/PREMORTEM.md`, `DISARM.md`, `OPTIONS.html` | premortem, disarm pass, decision room | written once; PLAN §4 cites the failures |
+| `docs/review-<date>.md` | feedback mode: the 7-section review spec | written once; decisions final |
+| `docs/<slug>.xlsx` | feedback mode: external contract for the team, committed | filled by humans, read back by `ll-implement` |
+
+Read, never rewritten: `docs/decide/OPENING.md` (from `ll-brainstorm` — everything in it is settled and the gate questions it already answers are not repeated), `docs/research-*/SUMMARY.md`, `docs/RETROSPECTIVE-*.md`.
+
+## Flow — project
+
+### 0. Mode, inputs and existing state
+Read the argument: `--measure` runs the disarm tests and may spend; without it the exercise is design-only (paper). When the request itself says which, that wins; otherwise announce the mode in one line — the owner overrules by replying. Read the project CLAUDE.md, `docs/decide/OPENING.md`, research summaries, and any record of a previous attempt ("segunda tentativa", a retrospective): the previous failure is a source in PLAN §11 with its dated reason, and its lessons enter §2/§4 with that source.
+
+Existing state at the root. `PLAN.md` already there from an earlier round, and that round is closed (its `PROGRESS.md` carries the `ll-close` epilogue, or the owner says it is closed) → `git mv` of what exists among `PLAN.md ROADMAP.md PROGRESS.md phases/ docs/decide/` into `docs/history/<round-slug>/` in one commit `docs(history): archive <round>`; `decisions/` and `BACKLOG.md` stay where they are and the DEC ids continue from the highest. Round not closed → stop and ask (band 1): close it with `ll-close`, or continue it. The new set is then written at the root, never under `docs/<project>/`.
+
+Read every reference the request names, before the gate:
+
+| Reference | How to read it |
+|---|---|
+| `https://claude.ai/code/artifact/<id>` | `Artifact` tool, `action: read`, `url` — returns the HTML; pixels via Playwright on a local copy |
+| a path on disk (html, png, pdf, docx) | `Read` (pdf by `pages`) |
+| any other URL | Playwright MCP headless: `mcp__plugin_playwright_playwright__browser_navigate`, then `browser_snapshot` or `browser_take_screenshot` |
+| a page that needs the owner's login | Chrome MCP (`claude-in-chrome`), his own session |
+| none of these returns the content | band-1 question: ask him to attach the file or paste the content — never an assumption about what it contains |
+
+"fiel ao protótipo" in the request makes the prototype a premise: its source is the content read, cited by artifact id or path. Without that content there is no premise and the gate stops.
+
+### 1. Premise gate (blocking)
+Five questions in one block, before any subagent: the number that decides success and what counts as FAILURE; the deliverable in the client's format; the source of truth for the data; the house pattern that applies; the constraint being invented out of caution that is not the owner's rule. The tool takes four per call: questions 1–4 in one call, the fifth right after, nothing in between. Skip every question `OPENING.md` already answers. Option shapes and why each question exists: `references/premise-gate.md`.
+
+The gate is passed when each of the five premises carries a source — `file:line`, the owner's message quoted, or an `ASM-n` label he has seen. A premise without a source is one question block (≤4) sent now, and nothing after this step runs — no premortem, no narrator, no subagent — until it is answered or ratified. A blanket delegation does not open this gate; it only turns band-2/3 premises into `ASM-n`.
+
+### 2. Back from the future
+Write the measured × faith inventory (5 sections) into `docs/decide/PREMORTEM.md`, then run 3–5 narrators (Opus, clean context, one persona each) that read only the inventory and the artifacts, never this conversation. Each writes `## ☠️ N.` deaths with a dated scene, an omen quoted literally from a project file with a named bias (or "no artifact mentions this point"), and a disarming test. Consolidate by convergence into F-01..F-0n ordered by lethality, TOP 3 marked, every quote re-opened and checked; close with "the missing rule" as a verifiable checklist. `references/premortem.md`.
+
+### 3. Disarm
+Design mode (default): for each F-0n, a design mitigation, a sentinel (the observable that says it is happening) and a plan B — into `docs/decide/DISARM.md`; each becomes R-nn in PLAN §4 and, when observable by command, a CA-nn in §6. Measure mode: an 8-part pre-registration per test, frozen and committed before anything runs; verdicts from the closed vocabulary with the number beside each; a "What this test does NOT prove" section; verdict ceiling when the ground truth is human. `references/disarm.md`.
+
+### 4. Decision room
+Write `docs/decide/OPTIONS.html` — self-contained: one alternatives table per topic (design, architecture, flow, data model) with what becomes true, cost, what is lost, revert cost and the recommendation, plus the fixed block with the five gate answers. A Fable judge in clean context (never fork) reads the file and the evidence and returns an opinion per topic; the opinion is appended to the file as its own section. The file is published, and its path given to the owner, before the first interview question. `references/decision-room.md`.
+
+### 5. Interview (blocking)
+A blanket delegation in the request ("pode decidir tudo", "me pergunta só o que for necessário") covers bands 2 and 3 only: those items become `ASM-n` and are never asked. Band 1 is asked anyway — money above the round's ceiling, irreversible outside the repo (deploy, destroy, credential in a new place, prod write), price or a promise to a customer, a scope cut, the number the owner will look at, an owner reference this session could not read, a recorded rule contradicted by new evidence. One block of ≤4 per round, ordered by impact, recommendation marked with its cost; the owner may answer "A" to ratify every recommended item at once. Ten minutes of silence ratify the recommended list (A), never a blocking item (B) and never a band-1 item.
+
+Count the decisions after step 4 and before the first question; number `n/N`; if the count grows, say "+k questions". Batteries of at most 4 per subject, ordered by impact, in the canonical format of `references/decision-policy.md` (fact with source, plain-words context, options with cost, recommendation first with its reason, "Claude decide" when delegable). Free text is a new requirement with its own ID, never an invalid answer; "Claude decide" is recorded as `ASM-n` and never asked again; an order against the recommendation gets one challenge with the cost named, then obeys. The helper `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/ll-implement/scripts/ll-tools.js` is used only if it exists — this skill does not ship it; when it is absent, take the next number after the highest in `decisions/`; with it, `dec-reserve <n>` reserves the ids before the battery. `references/interview.md`.
+
+### 6. Final round (blocking, always sent)
+Minimum contact: at least one message reaches the owner before PLAN.md is frozen, whatever the delegation was. It carries, in this order, (a) the decision count, (b) the counter `questions asked N / assumptions M / band-1 open K`, (c) the band-1 items still waiting for an answer, then every decision as it will be written — ID, decision, who decided, against-recommendation marks, assumptions. A run whose items are all band 2/3 still sends it, with `N = 0` and the ASM list. An item that was badly posed is re-asked here; a correction is applied and the list shown once more. "ok" or "A" freezes; ten minutes of silence ratifies the recommended list (A, the assumptions) and freezes PLAN.md too, but only when `band-1 open` is 0 — with one band-1 item open nothing freezes. Nothing is written before this round closes.
+
+### 7. Write the contract
+At the repo root: `PLAN.md` §0–§11, `ROADMAP.md` when phases > 3, one `decisions/DEC-NNNN-<slug>.md` per decision plus `decisions/README.md`, and an empty `PROGRESS.md` with the `<!-- ll-state -->` block — templates in `references/plan-skeleton.md`. The id is four digits with no project prefix (`DEC-0007-cents-mismatch.md`, never `DEC-X-007`), reserved with `ll-tools.js dec-reserve` when the helper exists and otherwise taken as the next number after the highest in `decisions/`. `plan-lint` reads phase plans only (an `ll-milestones` block), so it runs in `ll-implement`, not here; before freezing, check by hand that every `T<n>` and `CA-nn` carries a command, every `REQ-<slug>` points to one phase, and every `I-nn` has a source. Answer the self-sufficiency test in §10 before ending: which test key to use, what is missing, given that this session's context will be cleared.
+
+### 8. Hand off
+Report in Portuguese, opening with the counter `questions asked N / assumptions M / band-1 open K`, then the decision counts (owner / assumption / inherited / against recommendation), accepted risks, files written, hand-check result. With `N = 0` and `M > 5`, append one line under the phase heading of `PROGRESS.md`: `- review assumptions: <M> ASM written with 0 questions asked (<date>)`.
+
+Then stop and print the next command — one command, `ll-implement 1`, the attended run. An owner who wants the phases to run unattended may choose `ll-goal 1` instead; say it in the prose if he asks, never in the ▶ line. This skill does not write `phases/NN/PLAN.md`, does not dispatch executors and does not run a phase — the phase plan is written by `ll-implement` when the owner runs it, one phase at a time.
+
+## Flow — feedback
+
+### 1. Forensic ingestion (Sonnet, automatic)
+Take the material apart by format: `.docx` → unzip → `comments.xml` with the anchor text of each comment; PDF → visual `Read`, page by page; `.xlsx` → cell dump; an unreadable image → crop + upscale + read again. Close with the inventory "N comments, M visual annotations, K items" — every item gets an ID and none disappears from the triage. Recipes with exact commands: `references/feedback-ingestion.md`.
+
+### 2. Anchor in the code
+For every item, the current state: `file:line`, current price, current copy. An item that anchors nowhere becomes a question, not an assumption.
+
+### 3. Veracity gate
+List the factual claims the material proposes (times, prices, numbers, names, credits) and check each against `PRODUCT.md`, the project CLAUDE.md and the code. Divergences are the first questions, because they poison every decision after them. The instruction "the reviewers are lay people in X" means evaluate, not obey.
+
+### 4. Triage by impact
+Count the decisions before the first question. Order: money → offer → fact → copy → microcopy. Every question carries the reviewer's proposal, the anchored current state, the analysis and a recommendation; "reject" is always an option; in a scope question the maximalist option is always on the table. Anything for a human recipient asks the format once (`.xlsx` in `docs/`, artifact, issue) before being built.
+
+### 5. Blind arbitration (automatic)
+Two or more competing versions of conversion copy → judges (Fable, clean context, one per item) receive product facts, audience, criteria and the versions unattributed, with the `<output_contract>` (≤150 words: VERDICT / Rationale / Version D if better). Not asked whether to do it; the verdict comes back into the numbered question as "(retomada)". Contract: `references/review-spec.md`.
+
+### 6. The spec
+Write `docs/review-<date>.md` in the 7 sections: self-contained header · decision log including rejected items · §1–§N copy verbatim per page with target file · §Sweep greps of what became obsolete · §External dependencies with the placeholder rule · §Deferred with reason · §Verification contract. Decisions in it are final.
+
+### 7. External contract
+From §External dependencies, generate `docs/<slug>.xlsx` with checklist columns and a "how to use" tab, committed in the repo. Append the round to `ROADMAP.md` as a phase (`| NN | review <date> | … | PLANNED |` with a `## Phase NN` section whose success criteria are the §Verification contract and whose objective points at the spec). Report in Portuguese and stop: `▶ Next — /clear then ll-implement NN` (one executor per slice with a file allowlist).
+
+## Completion criterion
+
+Project: `PLAN.md` exists at the repo root with §0–§11 (`git ls-files PLAN.md PROGRESS.md` returns both at the root), §10 answers the self-sufficiency test, every CA-nn has a command, `decisions/README.md` counts match the DEC files and every id is `DEC-NNNN-<slug>.md`, `PROGRESS.md` carries the empty `ll-state` block, the premise gate closed with a source per premise, the final round was sent and closed, the counter `questions asked N / assumptions M / band-1 open K` is printed, no `phases/NN/PLAN.md` was written, and the hand check of step 7 found nothing. Feedback: the inventory count equals the number of decisions logged plus deferred items, and the `.xlsx` is committed.
+
+▶ Next — `/clear` then `ll-implement 1`   (feedback mode: `/clear` then `ll-implement NN`, the phase appended in step 7).
+
+## Questions
+
+- Gate: five, in one block, at the start; the ones `OPENING.md` answers are skipped. Blocking: no premortem, no subagent, no writing until every premise has a source.
+- Interview: batteries of at most 4 per subject, by impact, canonical format; counted before the first, `n/N` never renumbered. Feedback: counted before the first, one subject per call, money items alone.
+- Blanket delegation ("decide tudo"): covers bands 2 and 3; band-1 items are asked anyway, and an owner reference this session could not read is band 1.
+- Final round: always sent before writing, with the counter and the open band-1 list, even when zero questions were asked.
+- Never asked: the ten items of `references/decision-policy.md` (who executes, a fact readable from the repo, which pattern when a house pattern exists, a reversible detail inside a closed contract, another session's decision, out-of-scope subjects, a question that changes no action, copy without a commercial promise, industry defaults, the same policy question twice). Silence for 10 minutes ratifies the recommended option of a band-2/3 item, never option B and never band 1.
+
+## Models
+
+| Role | Model |
+|---|---|
+| Session | Fable |
+| Premortem narrators, research fronts | Opus, high, clean context |
+| Decision-room judge, copy judges | Fable, high, clean context — never fork |
+| Ingestion, anchoring, sweeps | Sonnet, medium |
+
+## References
+
+- Step 1 — the five questions, option shapes, where each answer lands: [references/premise-gate.md](references/premise-gate.md)
+- Step 2 — inventory template, narrator brief, death format, convergence, missing-rule checklist: [references/premortem.md](references/premortem.md)
+- Step 3 — design-mode table, 8-part pre-registration, verdict vocabulary, ceiling rule: [references/disarm.md](references/disarm.md)
+- Step 4 — OPTIONS.html structure and judge brief: [references/decision-room.md](references/decision-room.md)
+- Step 5–6 — battery construction, free text, final round, ASM and DEC recording: [references/interview.md](references/interview.md); question format, bands, never-ask list, silence rule: [references/decision-policy.md](references/decision-policy.md)
+- Step 7 — literal PLAN.md, ROADMAP.md, DEC, README and PROGRESS.md templates: [references/plan-skeleton.md](references/plan-skeleton.md)
+- Feedback 1–4 — ingestion recipes, inventory rule, anchoring, veracity gate: [references/feedback-ingestion.md](references/feedback-ingestion.md)
+- Feedback 5–7 — 7-section spec, blind arbitration contract, xlsx contract: [references/review-spec.md](references/review-spec.md)