# never ask twice

_Status: direction — as of 2026-07-16_
_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 blocked-stage
behavior, any human-input point in the pipeline, or ADR-0037's follow-on formalization ADR.

## Design

- **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.
- 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 at block time.** Before any question reaches the human, the blocked
     stage runs a mandatory, mechanical chain: `/os-adr:find` over the repo's ADRs first,
     then `/os-vault:query` over `domain/`/`tool/`/`convention/` facets. Only a genuine miss
     on both tiers produces a human-facing question.
  2. **Scope classification at mint time.** When the human unblocks a stage by answering,
     the factory asks one follow-up: "does this generalize beyond this repo?" No → record a
     repo-local ADR only. Yes → a vault convention note becomes the source of truth, and the
     repo ADR records the local adoption with a link back to it. The ask is not complete
     until the record exists — 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 across blocked-stage logs, not tracked live. A
     periodic audit (see [self-improvement-loops](self-improvement-loops.md)) sees the
     recurrence and promotes the answer to a vault convention.
- **Decision-category autonomy labels**, generalized from individual tickets to decision
  *categories* (e.g. dependency choice, schema-migration approach, UI flow pattern):
  - `afk-ready` + a covering record → proceed and cite the record.
  - `semi` → proceed, but flag the decision in the stage report for human review.
  - `hitl`, or no coverage at all → stop and ask.
  Promotion and demotion of categories happens only in periodic audits, never mid-run.
- **Cross-project answer, worked example:** a decision minted while building rails app A
  should be available when building rails app B. Repo ADRs are deliberately project-local
  (they record local adoption, not universal truth); the vault is the cross-project layer.
  os-sdlc doesn't change this split — it adds the lookup chain, the mint ritual, and the
  audit-driven promotion path on top of it.
- **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 categories graduate from `hitl`/`semi` to `afk-ready`; a
  category that graduates too early gets demoted, 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 the UI-flow decision category — would let front-end decisions start
  at `semi` instead of `hitl` from day one. This is horizon-scoped (see
  [horizon](horizon.md)) but validates that the category-autonomy frame generalizes to
  externally-sourced conventions, not just self-mined ones.
- This mechanism spans os-sdlc, os-adr, and os-vault jointly and gets its own ADR when
  formalized — it is not owned by any single plugin.

## Open questions

- Block-report format: what a blocked stage writes when it stops to ask (must carry enough
  context for the two-tier lookup to be re-run later without re-asking).
- Where decision-category labels live (ADR frontmatter? a small config file? vault note
  frontmatter?) and who assigns the initial label for a brand-new category.
- Audit cadence for promotion/demotion (tied to [self-improvement-loops](self-improvement-loops.md)'s
  ADR-audit loop, but not yet fixed).

## Sources

- ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
- os-adr `find`/`create` skills; os-vault `query`/`write` skills
- 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)
