3.5 KiB
| id | date | status | supersedes | superseded-by | affected-paths | affected-components | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 0044 | 2026-07-18 | Accepted |
|
|
0044 — Minimal-prompt discipline: prompt wording is added only in response to observed failures
Context
cc-os prompts (skill instructions, agent definitions, hook-assembled context) tend to accrete defensive wording over time — sentences added speculatively to head off imagined failure modes. This mirrors the pre-deterministic-gates instinct to have an agent's prompt do work that should instead be mechanically enforced. Unchecked, prompt bloat raises token cost, dilutes the sentences that matter, and makes it hard to tell which instructions are load-bearing versus vestigial. The os-sdlc pipeline-stages design (2026-07-18 grill) needed a governing rule for how the from-scratch orchestrator prompt and the named pipeline agents (test-writer, programmer, reviewer) should be written, and the user stated this as a general preference for all projects, not just cc-os.
Decision
Every prompt in cc-os — skill SKILL.md body, agent definition, and hook-assembled context packet — starts with the fewest sentences that state the job, the inputs, and the return format. Wording is added ONLY in response to an observed failure: an audit finding, an eval miss, or a broken run. Each addition must be traceable to the specific failure that justified it (e.g. a code comment, commit message, or doc note naming the failure). Any sentence in a prompt that cannot be traced to an observed failure is a deletion candidate. This is the prompt-level twin of the deterministic-gates philosophy (ADR governing mechanical enforcement over prose instruction): where gates push correctness out of prompts into hooks, minimal-prompt discipline keeps what remains in prompts lean and evidence-backed.
Consequences
Easier: prompts stay auditable — every sentence has a paper trail, so reviewing a prompt for bloat is a matter of checking traceability rather than re-deriving whether each sentence is still needed. Token cost per prompt stays low by construction. Harder: authors must resist the urge to preempt failure modes they can imagine but haven't observed; this requires discipline especially when a plausible-sounding safeguard has no incident behind it yet, and it means some real failures will happen once before their guard is written (accepted tradeoff — the alternative is unbounded preemptive bloat). Requires a lightweight convention (comment or note) for tracing each addition to its triggering failure, or the discipline degrades into an unenforced norm.
Alternatives rejected
Preemptive completeness (write every safeguard a designer can imagine up front) — rejected: this is exactly the failure mode that produced bloated, hard-to-audit prompts in prior art (DeltaRefinery and general experience with the mattpocock skills), and it front-loads cost for failures that may never occur. Periodic prompt review/pruning on a schedule instead of failure-triggered — rejected: schedule-based review still requires someone to guess which sentences are load-bearing without a traceability record, and doesn't prevent bloat from accumulating between reviews. No governing rule, leave it to author judgment per prompt — rejected: judgment alone is what produced the current inconsistency across cc-os prompts; a stated, citable rule is needed so any prompt-editing session (human or AI) has a shared bar.