| name | refine-approach |
| description | 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. |
| argument-hint | path to a doc in docs/brainstorm/ or docs/exec-plans/ |
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.
