Improve propose skill with brainstorming-inspired discovery process

.agents/skills/propose/SKILL.md

@@ -1,19 +1,34 @@
 ---
 name: propose
-description: Write high-quality proposal docs for this repository using the established propose style. Use when the user asks to create, update, or review files under `propose/`, or requests a "proposal/propose" before implementation.
+description: Write high-quality proposal docs for this repository using the established propose style and systematic discovery process. Use when the user asks to create, update, or review files under `propose/`, or requests a "proposal/propose" before implementation.
 disable-model-invocation: true
 ---
 
 # Propose Skill
 
-Create proposal docs that match this repository's accepted style and workflow.
+Create proposal docs that match this repository's accepted style and workflow through systematic discovery and validation.
+
+## Hard Gate
+
+Do NOT write the proposal document until you have:
+1. Explored the context
+2. Asked clarifying questions
+3. Presented approaches and gotten alignment
+4. Drafted the proposal sections with approval
+
+This applies to ALL proposals regardless of perceived simplicity.
+
+## Anti-Pattern: "This Is Too Simple To Need Discovery"
+
+Every proposal goes through this process. A small tool addition, a documentation change, a schema tweak — all of them. "Simple" proposals are where unexamined assumptions cause the most rework. The discovery can be brief for truly simple work, but you MUST do it.
 
 ## When to use
 
 Use this skill when:
 - the user asks for a new proposal in `propose/active/`
 - the user asks to refine an existing proposal
 - work is non-trivial and should be proposed before implementation
+- the user asks "should we propose this first?"
 
 Do not use this skill for small one-file bug fixes or purely mechanical edits.
 
@@ -23,13 +38,113 @@ If the work is expected to ship as multiple implementation PRs, create/update
 the proposal here first, then hand off plan authoring to
 `../plan/SKILL.md` for the execution split and per-PR delivery contract.
 
-## Required repo context
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore repo context** — check README.md, CODEBASE_REQUIREMENTS.md, relevant existing proposals, recent commits
+2. **Ask clarifying questions** — one at a time, determine what to ask based on context and topic. Focus on understanding the real problem, constraints, success criteria
+3. **Propose 2-3 approaches** — with trade-offs and your recommendation
+4. **Draft proposal sections** — present each section and get approval before moving to the next
+5. **Write proposal file** — save to `propose/active/<TOPIC>-PROPOSE.md`
+6. **Self-review** — check for quality issues inline
+7. **User review gate** — ask user to review the written proposal
+8. **Complete** — mark proposal ready for implementation planning
+
+## Process Flow
+
+```dot
+digraph propose_flow {
+    "Explore repo context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Draft proposal sections" [shape=box];
+    "User approves section?" [shape=diamond];
+    "Write proposal file" [shape=box];
+    "Self-review (fix inline)" [shape=box];
+    "User reviews proposal?" [shape=diamond];
+    "Complete" [shape=doublecircle];
+
+    "Explore repo context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Draft proposal sections";
+    "Draft proposal sections" -> "User approves section?";
+    "User approves section?" -> "Draft proposal sections" [label="no, revise"];
+    "User approves section?" -> "Write proposal file" [label="yes"];
+    "Write proposal file" -> "Self-review (fix inline)";
+    "Self-review (fix inline)" -> "User reviews proposal?";
+    "User reviews proposal?" -> "Write proposal file" [label="changes requested"];
+    "User reviews proposal?" -> "Complete" [label="approved"];
+}
+```
+
+## The Process
+
+**1. Explore repo context:**
+
+Before asking anything, read:
+- `README.md` — public surface, env vars, ontology/reindex implications
+- `CODEBASE_REQUIREMENTS.md` — brownfield assumptions and source mapping
+- Relevant existing proposals under `propose/active/`
+- Recent commits in the target area
+
+**2. Ask clarifying questions:**
+
+Ask questions ONE AT A TIME to refine the proposal. You determine what to ask based on:
+- What you don't understand about the problem
+- What seems ambiguous or underspecified
+- What alternatives exist
+- What constraints or dependencies matter
+
+**Prefer multiple choice questions when possible, but open-ended is fine too.**
+
+Only one question per message. If a topic needs more exploration, break it into multiple questions.
+
+Focus on understanding:
+- The real problem (vs symptoms)
+- Success criteria
+- Constraints and dependencies
+- What's explicitly out of scope
+
+**3. Propose approaches:**
 
-Before drafting, read:
-1. `README.md` (public surface, env vars, ontology/reindex implications)
-2. `CODEBASE_REQUIREMENTS.md` (brownfield assumptions and source mapping)
-3. Relevant active plan/propose docs under `plans/active/` and `propose/active/`
-4. The target area's implementation files (only as needed)
+Once you understand the problem space, present 2-3 different solution approaches:
+- Lead with your recommended option and explain why
+- Include trade-offs for each option
+- Be specific about what each approach means
+
+Present options conversationally. Wait for user alignment before proceeding.
+
+**4. Draft proposal sections:**
+
+Once aligned on an approach, draft the proposal section by section:
+- Present each section and ask "Does this look right?"
+- Wait for approval before moving to the next section
+- Scale sections to complexity: a few sentences if straightforward, more detail if nuanced
+
+**5. Write the proposal file:**
+
+After section approval, write the complete proposal to `propose/active/<TOPIC>-PROPOSE.md`
+
+Use the standard structure (below) adapted to the topic's complexity.
+
+**6. Self-review:**
+
+Immediately after writing the proposal, review it for:
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague statements? Fix them.
+2. **Internal consistency:** Do sections contradict each other? Does the scope match the proposed solution?
+3. **Quality bar check:** Does it meet the quality criteria below?
+4. **Ambiguity check:** Could anything be interpreted two different ways? Pick one and make it explicit.
+
+Fix any issues inline. No need to re-review — just fix and move on.
+
+**7. User review gate:**
+
+After self-review passes, ask the user:
+
+> "Proposal written to `propose/active/<TOPIC>-PROPOSE.md`. Please review it and let me know if you want any changes before we proceed."
+
+Wait for the user's response. If they request changes, make them and re-run the self-review loop. Only mark complete once the user approves.
 
 ## Proposal quality bar (based on merged PR patterns)
 
@@ -128,6 +243,15 @@ Docs-only; baseline unchanged.
 - [ ] Out-of-scope section is present
 - [ ] Sequencing/follow-up path is clear
 
+## Key Principles
+
+- **One question at a time** — Don't overwhelm with multiple questions
+- **Multiple choice preferred** — Easier to answer than open-ended when possible
+- **Agent determines questions** — You figure out what to ask based on context
+- **Explore alternatives** — Always propose 2-3 approaches before settling
+- **Incremental validation** — Present sections, get approval before moving on
+- **Be flexible** — Go back and clarify when something doesn't make sense
+
 ## Additional resources
 
 - See practical examples in [reference.md](reference.md).