Reference Before Plan
Use this skill when external references must shape the plan before implementation.
Prime Agent Setup
Read ../../../../references/prime-planning-workflow.md and state-and-config.md — both normative — and follow their setup, state, language, and reviewer/criticizer rules. State lives in .git/prime_plans/ via ../../../../scripts/prime_plans_state.py init --workdir <target-workdir>; spawn reviewer/criticizer roles with await rlm(...).
Required Reference Flow
- Inspect the target Git repo read-only before external research so search terms match the actual codebase and constraints.
- Create the
.git/prime_plans run state and planning artifact directory once the topic is clear.
- Search proactively for related projects, articles, papers, docs, and prior art. Prefer the Prime Agent
websearch skill; use tools such as gh only when already available.
- Download or clone at least 3 credible references before writing
PLAN_v1.md; store large downloads outside the target repo under ~/.cache/prime-plans/refs/<repo-slug>/<topic>/. Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.
- For every reference, record source metadata and local path in
REF_ANALYSIS.md and .git/prime_plans/runs/<run-id>/refs.jsonl: title, URL, kind, retrieval method, date accessed, local path, coverage, and evidence gaps.
- For every reference, produce a structured analysis artifact before asking adoption questions. If
graphify is installed, generate JSON beside the local reference and record the path. If missing, ask one yes/no question about installing it locally; this install question must not offer Auto-complete. On refusal, do a manual structured read and record the waiver in REF_ANALYSIS.md.
- For every reference after analysis, ask at least 3 ref-specific adoption questions before using its ideas in
PLAN_v1.md; each based on downloaded content, recommended option first, Other second-last, Auto-complete last.
- Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum.
Auto-complete cannot grant this waiver.
- Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement, no refinement limit, at most five high-priority comments or questions per refinement round.
REF_ANALYSIS.md
Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; local download paths; structured analysis or graph JSON paths; adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.
Reference ideas are not eligible for PLAN_v1.md until their adoption question answers are recorded.
1---2name: reference-before-plan3description: Research references before creating a Prime Agent plan. Use when repo-change planning needs downloaded projects, articles, papers, docs, per-reference analysis, adoption questions, language settings, and reviewer or criticizer subagents; exclude direct implementation-only, factual/explanation, trivial command-only, or explicit no-plan requests.4---56# Reference Before Plan78Use this skill when external references must shape the plan before implementation.910## Prime Agent Setup1112Read `../../../../references/prime-planning-workflow.md` and `state-and-config.md` — both normative — and follow their setup, state, `language`, and reviewer/criticizer rules. State lives in `.git/prime_plans/` via `../../../../scripts/prime_plans_state.py init --workdir <target-workdir>`; spawn reviewer/criticizer roles with `await rlm(...)`.1314## Required Reference Flow15161. Inspect the target Git repo read-only before external research so search terms match the actual codebase and constraints.172. Create the `.git/prime_plans` run state and planning artifact directory once the topic is clear.183. Search proactively for related projects, articles, papers, docs, and prior art. Prefer the Prime Agent `websearch` skill; use tools such as `gh` only when already available.194. Download or clone at least 3 credible references before writing `PLAN_v1.md`; store large downloads outside the target repo under `~/.cache/prime-plans/refs/<repo-slug>/<topic>/`. Landing pages, README-only snapshots, abstracts, package metadata, or curl-only fragments do not count when deeper source material is available.205. For every reference, record source metadata and local path in `REF_ANALYSIS.md` and `.git/prime_plans/runs/<run-id>/refs.jsonl`: title, URL, kind, retrieval method, date accessed, local path, coverage, and evidence gaps.216. For every reference, produce a structured analysis artifact before asking adoption questions. If `graphify` is installed, generate JSON beside the local reference and record the path. If missing, ask one yes/no question about installing it locally; this install question must not offer `Auto-complete`. On refusal, do a manual structured read and record the waiver in `REF_ANALYSIS.md`.227. For every reference after analysis, ask at least 3 ref-specific adoption questions before using its ideas in `PLAN_v1.md`; each based on downloaded content, recommended option first, `Other` second-last, `Auto-complete` last.238. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or waives the minimum. `Auto-complete` cannot grant this waiver.249. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement, no refinement limit, at most five high-priority comments or questions per refinement round.2526## REF_ANALYSIS.md2728Include: original request and repo evidence that shaped the search; attempted queries and selection criteria; references selected and rejected; local download paths; structured analysis or graph JSON paths; adoption questions and recorded answers; accepted ideas, rejected ideas, and reasons; evidence gaps and user-granted waivers; language, reviewer, and criticizer settings used.2930Reference ideas are not eligible for `PLAN_v1.md` until their adoption question answers are recorded.
Optim-Agent