From 30a6862f601265d616a85076463d07020af96934 Mon Sep 17 00:00:00 2001 From: Dmitry Teryaev Date: Sun, 7 Jun 2026 11:43:52 +0300 Subject: [PATCH 1/2] Update propose skill with brainstorming-inspired discovery process - Add Hard Gate: prevent writing proposals without discovery - Add systematic 8-step process with task tracking - Agent determines clarifying questions (not scripted) - Present 2-3 solution approaches with trade-offs - Draft sections incrementally with approval - Self-review after writing - User review gate before completion Co-Authored-By: Claude Opus 4.7 --- .agents/skills/propose/SKILL.md | 145 ++++++++++++++++++++++++++++---- 1 file changed, 130 insertions(+), 15 deletions(-) diff --git a/.agents/skills/propose/SKILL.md b/.agents/skills/propose/SKILL.md index 66d33886..a93badca 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:** + +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." -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) +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) @@ -119,14 +234,14 @@ Docs-only; baseline unchanged. - `TOOL-NAME-PROPOSE.md` - `ARCHITECTURE-CHANGE-PROPOSE.md` -## Final checklist +## Key Principles -- [ ] Proposal file lives under `propose/active/` -- [ ] Problem statement includes concrete examples -- [ ] Schema/ontology/re-index impact is explicit -- [ ] Open questions include `[TBD]` with recommendations -- [ ] Out-of-scope section is present -- [ ] Sequencing/follow-up path is clear +- **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 From cb3511f030f0bf2ce32e90a17b04f9e8dff0ca14 Mon Sep 17 00:00:00 2001 From: Dmitry Teryaev Date: Sun, 7 Jun 2026 11:49:45 +0300 Subject: [PATCH 2/2] fix: restore Final checklist section that was accidentally omitted Co-Authored-By: Claude Opus 4.7 --- .agents/skills/propose/SKILL.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.agents/skills/propose/SKILL.md b/.agents/skills/propose/SKILL.md index a93badca..7083f30f 100644 --- a/.agents/skills/propose/SKILL.md +++ b/.agents/skills/propose/SKILL.md @@ -234,6 +234,15 @@ Docs-only; baseline unchanged. - `TOOL-NAME-PROPOSE.md` - `ARCHITECTURE-CHANGE-PROPOSE.md` +## Final checklist + +- [ ] Proposal file lives under `propose/active/` +- [ ] Problem statement includes concrete examples +- [ ] Schema/ontology/re-index impact is explicit +- [ ] Open questions include `[TBD]` with recommendations +- [ ] 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