77 lines
4.9 KiB
Markdown
77 lines
4.9 KiB
Markdown
|
# 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), [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)
|