diff --git a/.agents/skills/propose/SKILL.md b/.agents/skills/propose/SKILL.md index 66d33886..7083f30f 100644 --- a/.agents/skills/propose/SKILL.md +++ b/.agents/skills/propose/SKILL.md @@ -1,12 +1,26 @@ --- 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 @@ -14,6 +28,7 @@ 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/-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/-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/-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).