Refine Approach
Improve a thinking document in place — a brainstorm or a plan. Not a rewrite, not new scope: tighter, clearer, more honest.
Step 1 — Get the doc
Given a path, read it whole. Otherwise list docs/brainstorm/ and docs/exec-plans/backlog/ (+ active/) and ask which.
Step 2 — Interrogate it (answer from the doc + codebase where you can)
- Unclear? A step a fresh agent would misread.
- Unnecessary? Hypotheticals, gold-plating (solo app, ~1k users, no backend) → cut.
- Avoided? A hard decision left implicit that
/build will trip over (Hive schema change, navigation, splash preload).
- Assumed? A pattern claimed but not verified — grep for the bloc/repo/route.
- At risk? Users' cached boxes, permissions, Play policy, version bump — under-treated?
- Underestimated? A phase that's really three, or a "simple" change that crosses layers.
Step 3 — Score (Weak / OK / Strong, one line each)
- Clarity 2. Completeness (every criterion has a
verify:; analyze + test are gates) 3. Specificity (real paths, real class names, real commands) 4. YAGNI 5. Scope (one PR / sane phases).
Step 4 — Flag the one thing
Name the single most important issue first.
Step 5 — Improve in place
- Minor fixes (wording, a missing path, a
verify:, marking an assumption) → apply.
- Substantive (dropping a requirement, restructuring phases, splitting) → propose, get approval, apply.
- Edit the existing file; keep its structure and frontmatter; update
timestamp. Update the docs/exec-plans/index.md row if a plan's problem statement or dependencies changed.
Step 6 — Handoff
Brainstorm refined → /grill-me, then /plan. Plan refined → /build, or /grill-me for a final pass. After two passes, recommend shipping.
What NOT to do
- Rewrite the whole doc. Add requirements never discussed. Create a separate review file. Remove real constraints, rationale, or open questions.
1---2name: refine-approach3description: Sharpen an existing brainstorm or execution plan for The Holy Qur'an app — score it for clarity, completeness, specificity, YAGNI, and scope, then improve it in place. Use when the user says "refine this", "tighten the plan", "review the approach", or after brainstorming/planning to harden the doc before building.4---56# Refine Approach78Improve a **thinking document** in place — a brainstorm or a plan. Not a rewrite, not new scope: tighter, clearer, more honest.910## Step 1 — Get the doc11Given a path, read it whole. Otherwise list `docs/brainstorm/` and `docs/exec-plans/backlog/` (+ `active/`) and ask which.1213## Step 2 — Interrogate it (answer from the doc + codebase where you can)14- **Unclear?** A step a fresh agent would misread.15- **Unnecessary?** Hypotheticals, gold-plating (solo app, ~1k users, no backend) → cut.16- **Avoided?** A hard decision left implicit that `/build` will trip over (Hive schema change, navigation, splash preload).17- **Assumed?** A pattern claimed but not verified — grep for the bloc/repo/route.18- **At risk?** Users' cached boxes, permissions, Play policy, version bump — under-treated?19- **Underestimated?** A phase that's really three, or a "simple" change that crosses layers.2021## Step 3 — Score (Weak / OK / Strong, one line each)221. **Clarity** 2. **Completeness** (every criterion has a `verify:`; analyze + test are gates) 3. **Specificity** (real paths, real class names, real commands) 4. **YAGNI** 5. **Scope** (one PR / sane phases).2324## Step 4 — Flag the one thing25Name the single most important issue first.2627## Step 5 — Improve in place28- Minor fixes (wording, a missing path, a `verify:`, marking an assumption) → apply.29- Substantive (dropping a requirement, restructuring phases, splitting) → propose, get approval, apply.30- Edit the existing file; keep its structure and frontmatter; update `timestamp`. Update the `docs/exec-plans/index.md` row if a plan's problem statement or dependencies changed.3132## Step 6 — Handoff33Brainstorm refined → `/grill-me`, then `/plan`. Plan refined → `/build`, or `/grill-me` for a final pass. After two passes, recommend shipping.3435## What NOT to do36- Rewrite the whole doc. Add requirements never discussed. Create a separate review file. Remove real constraints, rationale, or open questions.
mhmzdev