120 lines
8.4 KiB
Markdown
120 lines
8.4 KiB
Markdown
# never ask twice
|
|
|
|
_Status: settled — grilled 2026-07-18_
|
|
_Connects to: [self-improvement-loops](self-improvement-loops.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [standards-and-conventions](standards-and-conventions.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_
|
|
|
|
## Purpose
|
|
|
|
The agency mechanism, and the most important node in this reference set. States the
|
|
operating principle that lets the factory earn autonomy over time instead of asking the
|
|
human the same question on every run. Load this before designing any human-input point in
|
|
the ideation phases (grill / to-spec / to-tickets), or any spec-gap handling in the
|
|
pipeline. Formalized 2026-07-18 in its own cross-plugin ADR (see Sources).
|
|
|
|
## Design (settled 2026-07-18)
|
|
|
|
- **Operating principle: the factory never asks the human the same question twice.** Trust
|
|
is earned in units, and every unit is made durable and reusable. Goal state: the human is
|
|
only presented options when the factory genuinely needs direction — not because a decision
|
|
that was already made once was forgotten.
|
|
- **Home: the ideation phases, not the implementation pipeline.** Questions to the human
|
|
belong in grill / to-spec / to-tickets; by the time tickets exist, all decisions are made
|
|
and implementation is nearly mechanical, with standards and conventions baked into lint
|
|
rules and agent prompts/reference material
|
|
([standards-and-conventions](standards-and-conventions.md)). The pipeline keeps one thin
|
|
safety valve: a spec gap surfacing mid-implementation is a **defect in the ticket** — the
|
|
run fails back to the spec layer (where the answer gets minted into the ticket/records),
|
|
never an inline chat ask. "All decisions made by to-tickets" is the target state the
|
|
system converges toward, not an assumption it depends on.
|
|
- No new storage system and no literal decision-tree engine. The "tree" is the existing ADR
|
|
corpus plus vault conventions; os-sdlc adds only wiring on top of os-adr and os-vault.
|
|
Three thin pieces:
|
|
1. **Two-tier lookup as a pre-pass.** When a grill / to-spec / to-tickets session loads
|
|
its target, it runs one batched lookup pass — `/os-adr:find` over the repo's ADRs,
|
|
then `/os-vault:query` over the relevant `domain/`/`tool/`/`convention/` facets — and
|
|
drafts questions *against* that corpus: a question already answered by a record never
|
|
gets drafted; the record gets cited instead. Topic-shift rule: if the interview moves
|
|
outside the pre-pass scope, re-run the lookup for the new topic before asking.
|
|
2. **Mint in batch at settle.** Answers accumulate during the interview in a running
|
|
decisions-so-far list (the crash/resume mitigation); at the settle step the skill
|
|
proposes a scope classification for the whole batch ("these are repo ADRs, this one
|
|
generalizes → vault convention — confirm/amend"), the human confirms once, and it
|
|
mints everything. **The session is not complete until the mint pass has run** — an
|
|
answered-but-unrecorded question is the failure mode this whole mechanism exists to
|
|
prevent.
|
|
3. **Promotion by audit, not memory.** A decision minted local that later blocks a second
|
|
project is a recurrence — visible in session/spec-gap exhaust, not tracked live.
|
|
Periodic audits (owned by [self-improvement-loops](self-improvement-loops.md)) see the
|
|
recurrence and promote the answer to a vault convention. Promotion and demotion happen
|
|
only in audits, never mid-run; the cadence is self-improvement-loops' decision.
|
|
- **ADR↔convention delineation:** conventions are defaults that hold until overridden; ADRs
|
|
are project-local adoptions of, or deviations from, them. Worked example: "always use
|
|
Devise for Rails auth" is a vault convention note (`convention/rails`, `tool/devise`,
|
|
`domain/authentication`), not an ADR anywhere; the client project that can't use Devise
|
|
records a repo ADR deviating from the convention, linking it. The mint-time scope
|
|
question and the audit are the *only* boundary machinery — no dedicated promotion skill,
|
|
no new taxonomy (the six flat ADR-011 facets are the domain organization the grill
|
|
pre-pass queries).
|
|
- **Two-state readiness, not three-tier autonomy.** The former `hitl`/`semi`/`afk-ready`
|
|
decision-category labels are retired (superseding ADR in Sources): the `semi`/`hitl`
|
|
boundary had no operational test, and artifact/PR review already delivers
|
|
proceed-and-flag for free. In their place:
|
|
- **Coverage is two-state.** A decision category is either covered (a record exists →
|
|
proceed and cite it in the artifact, where review catches mistakes) or uncovered
|
|
(ask). Coverage *is* the record's existence — no label field, no config surface.
|
|
- **Tickets are two-state**, adopting Matt Pocock's triage vocabulary:
|
|
`ready-for-agent` ("fully specified — an agent can complete it without asking",
|
|
falsifiable in production: an agent that asks or bounces proves the label wrong) and
|
|
`ready-for-human`. A ticket that is neither is under-decomposed — split it into
|
|
ordered agent/human parts, agent parts first where dependencies allow — never labeled
|
|
into limbo. This replaces the autonomy trio in os-backlog's label taxonomy (migration
|
|
of existing tickets tracked as a follow-up issue).
|
|
- **Honest limit:** this mechanism guarantees the *plumbing* — a decision recorded once is
|
|
findable everywhere it applies — not the *judgment* that the agent applies the right
|
|
convention in an ambiguous case. Judgment quality is proven only by accumulated audits.
|
|
Expect the ask-rate to fall as the convention corpus grows and coverage widens; a
|
|
mis-minted convention gets caught at artifact review or demoted by audit, with the ADR
|
|
trail showing exactly which decision went wrong and why.
|
|
- **Mobbin** (mobbin.com, a design-pattern reference library) as a future pre-seeded
|
|
convention library for UI-flow decisions — pre-seeding makes a category *covered* from
|
|
day one. Horizon-scoped (see [horizon](horizon.md)), but validates that the coverage
|
|
frame generalizes to externally-sourced conventions, not just self-mined ones.
|
|
- This mechanism spans os-sdlc, os-adr, os-vault, and os-backlog jointly; formalized in its
|
|
own ADR (see Sources) rather than owned by any single plugin.
|
|
|
|
## Resolved 2026-07-18 (grill)
|
|
|
|
1. **Home** — ideation-primary; pipeline keeps only a fail-back-to-spec-layer valve for
|
|
ticket defects; never inline asks mid-implementation.
|
|
2. **Lookup mechanics** — one batched pre-pass at session load + topic-shift re-lookup,
|
|
not per-question inline lookups.
|
|
3. **Delineation** — mint-time scope question + audit promotion are the entire
|
|
ADR↔convention boundary; no dedicated promotion machinery.
|
|
4. **Mint mechanics** — batch at settle with a running decisions list; session incomplete
|
|
until minted.
|
|
5. **Labels** — three-tier autonomy retired for two-state coverage (records) and two-state
|
|
readiness (tickets, `ready-for-agent`/`ready-for-human`); under-decomposed tickets get
|
|
split, not a third label. Existing-ticket migration is a tracked os-backlog follow-up.
|
|
6. **Audit cadence** — contract fixed here (audit-only promotion/demotion, never mid-run);
|
|
the cadence number is deferred to [self-improvement-loops](self-improvement-loops.md).
|
|
7. **Formalization** — two ADRs minted at settle: the cross-plugin never-ask-twice
|
|
mechanism, and the superseding label-taxonomy change.
|
|
|
|
No open questions remain in this doc. The former "block-report format" question dissolved
|
|
with the reframe: a mid-implementation gap is a ticket defect routed to the spec layer, and
|
|
its report format belongs to [spec-and-ticket-layer](spec-and-ticket-layer.md) /
|
|
[pipeline-stages](pipeline-stages.md), not here.
|
|
|
|
## Sources
|
|
|
|
- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
|
|
- Never-ask-twice formalization ADR + label-taxonomy superseding ADR (minted 2026-07-18 at
|
|
this grill's settle; see `docs/adr/README.md` index)
|
|
- Matt Pocock's `/triage` skill (two categories, five states incl. `ready-for-agent` /
|
|
`ready-for-human`) — vocabulary source for two-state readiness
|
|
- os-adr `find`/`create` skills; os-vault `query`/`write` skills; os-backlog ten-label
|
|
taxonomy (`plugins/os-backlog/skills/route/SKILL.md`)
|
|
- SecondBrain vault: taxonomy/ladder note (referenced by [horizon](horizon.md))
|
|
- mobbin.com (design-pattern library, horizon reference)
|
|
- 2026-07-16 design session (this doc's origin); 2026-07-18 grill (this settle)
|