Reference Before Plan
Use this skill when external references must shape the plan before implementation.
Setup
- Read
../_shared/references/prime-planning-workflow.md, ../_shared/references/state-and-config.md, and ../_shared/references/plan-artifact-template.md.
- Initialize state with
python3 scripts/optim_plans.py init --repo <target-repo> --topic <topic> --plan-level reference-before-plan --request-text <original-request>.
- Use
.git/optim-plans for controller state and docs/optim-plans/YYYY-MM-DD-topic/ for public artifacts.
Required Reference Flow
- Inspect the target Git repo read-only before external research so search terms match the actual codebase.
- Search proactively for related projects, articles, papers, docs, and prior art.
- Download or clone at least 3 credible references before writing
PLAN_v1.md. Store large downloads outside the target repo by default under ~/.cache/optim-plans/refs/<repo-slug>/<topic>/.
- Record source metadata with
record-reference: title, URL, kind, retrieval method, access date, local path, coverage, and evidence gaps.
- For every reference, produce a structured analysis artifact and record it with
record-reference-analysis. If a richer parser is unavailable, do a manual structured read and record any waiver with record-reference-waiver.
- For every reference after analysis, ask at least 3 ref-specific adoption questions before using its ideas in
PLAN_v1.md. Each question must be based on downloaded content, put the recommended option first, put Other second-last, and put Auto-complete last.
- Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or grants a waiver.
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, and at most five high-priority comments or questions per refinement round.
REF_ANALYSIS.md
Include original request, repo evidence, attempted queries, selection criteria, selected and rejected references, local paths, structured analysis paths, adoption questions and answers, accepted ideas, rejected ideas, evidence gaps, user-granted waivers, and reviewer/criticizer settings used for the run.
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---5
6# Reference Before Plan
7
8Use this skill when external references must shape the plan before implementation.
9
10## Setup
11
121. Read `../_shared/references/prime-planning-workflow.md`, `../_shared/references/state-and-config.md`, and `../_shared/references/plan-artifact-template.md`.
132. Initialize state with `python3 scripts/optim_plans.py init --repo <target-repo> --topic <topic> --plan-level reference-before-plan --request-text <original-request>`.
143. Use `.git/optim-plans` for controller state and `docs/optim-plans/YYYY-MM-DD-topic/` for public artifacts.
15
16## Required Reference Flow
17
181. Inspect the target Git repo read-only before external research so search terms match the actual codebase.
192. Search proactively for related projects, articles, papers, docs, and prior art.
203. Download or clone at least 3 credible references before writing `PLAN_v1.md`. Store large downloads outside the target repo by default under `~/.cache/optim-plans/refs/<repo-slug>/<topic>/`.
214. Record source metadata with `record-reference`: title, URL, kind, retrieval method, access date, local path, coverage, and evidence gaps.
225. For every reference, produce a structured analysis artifact and record it with `record-reference-analysis`. If a richer parser is unavailable, do a manual structured read and record any waiver with `record-reference-waiver`.
236. For every reference after analysis, ask at least 3 ref-specific adoption questions before using its ideas in `PLAN_v1.md`. Each question must be based on downloaded content, put the recommended option first, put `Other` second-last, and put `Auto-complete` last.
247. Block rather than pad if fewer than 3 credible references exist, unless the user explicitly narrows the topic or grants a waiver. `Auto-complete` cannot grant this waiver.
258. Continue with big-plan depth: at least 10 planning questions, required web research during brainstorming and refinement, no refinement limit, and at most five high-priority comments or questions per refinement round.
26
27## REF_ANALYSIS.md
28
29Include original request, repo evidence, attempted queries, selection criteria, selected and rejected references, local paths, structured analysis paths, adoption questions and answers, accepted ideas, rejected ideas, evidence gaps, user-granted waivers, and reviewer/criticizer settings used for the run.
30
31Reference ideas are not eligible for `PLAN_v1.md` until their adoption question answers are recorded.
majiayu000