research-brief
Skill0 starsChanged 3 months agoMITView on GitHub
Use when you need to hand a research task to a separate deep-research executor — ChatGPT-Pro (remote-fetch) or another Claude/Claude Code session with direct repo access (local-session) — and want the comprehensive prompt authored here, with full repo access, instead of reconstructing it in a throwaway session. Interviews you to ~95% confidence, then emits a self-contained, paste-ready requirements prompt and (remote-fetch executor, fetchable repo only) refreshes the upload manifest — a repository the remote-fetch executor cannot access takes the remote-fetch (inline) variant: fully self-contained, no manifest. Triggers: needing a next spec/feature, a thorny fix, a hardening pass, or a foundational/doc overhaul deep-researched in another session. Produces: reports/<topic>-research-brief.md + (remote-fetch, fetchable repo only) a refreshed reports/manifest_<date>_<shortsha>.txt. Mutates: only reports/ on user approval. Not for a bounded question that can be answered in this session — that is the `research` skill.
20 other projects use a version of this.
Adopted by
Most recently taken up by
- jacarty/claude-toolkittheir own version, first seen Nov 15, 2026
- Kuan-AI-com/agent-skillstheir own version, first seen Nov 15, 2026
- Suryanandx/qvac-uitheir own version, first seen Nov 1, 2026
- Nomanriaz786/claude-consulting-teamtheir own version, first seen Nov 1, 2026
- Evan-Daruwalla/claude-skill-suitetheir own version, first seen Oct 20, 2026
- dss-time/repo-doctor-skillstheir own version, first seen Oct 15, 2026
Used with
Projects with it also use meeting-notes and weekly-review.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
claude-office-skillsSkillmeeting-notes
>
Also in 3 projects that use this
QuixiAISkillweekly-review
Review the past week across goals, tasks, calendar, journal, and commitments, then propose the next week
Also in 3 projects that use this
Other versions20 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 20
- OpenHands/extensions★ 167same name
- duncan-buildroom/freeskills★ 65same name
- Mikefluff/skills★ 26same name
- charlie947/life-automation-skills★ 25same name
- Heuresis/YouTube-Agency★ 15same name
- TheCraigHewitt/cowork-starter-pack★ 5same name
- robertbradley-oss/skills★ 2same name
- alectivism/maven-template★ 1same name
- dss-time/repo-doctor-skills★ 1same name
- molly-diversifiedfun/claude-skills★ 1same name
10 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- codebase-designSkill
- code-reviewSkill
- commission-method-gap-researchSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- grillingSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- improve-codebase-architectureSkill
- method-gap-research-statusSkill
- prototypeSkill
- refactor-skillSkill
- researchSkill
- setup-matt-pocock-skillsSkill
- skill-evidence-captureSkill
- skill-evolutionSkill
- skill-evolution-statusSkill
- tddSkill
- teachSkill
- to-issuesSkill
- to-prdSkill
- triageSkill
- wait-whatSkill
- wayfinderSkill
- writing-great-skillsSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 3 are distinctive, and 4 are very specific to this project.
0
Common
Most of the 19 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Do NOT Write the brief file or refresh the manifest until BOTH hold: (a) confidence has reached ~95% — via the interview, OR via an …
- Very specific: line 37
Read references/brief-template.md in full.
- Distinctive: line 106
Before writing, present in chat:
- Very specific: line 145
Repeat-run brief already at the target path: When reports/<topic>-research-brief.md already exists from an earlier run or session, you must …
- Very specific: line 153
Use this closeout checklist before the final response.
- Distinctive: line 176
This session authors; Session 2 researches: Don't perform the deep research here.
- Very specific: line 178
Mutates only
reports/: Never touch docs/, specs/, .claude/skills/, or source.
“Common” is measured: kept by at least 6 in 10 of the 19 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Research Brief
Author the comprehensive, paste-ready prompt for a separate deep-research session — ChatGPT-Pro by default, or another Claude/Claude Code session — here, where Claude has direct access to the whole repository, instead of reconstructing it interactively in the consuming session.
This skill replaces "Session 1" of a two-stage routine:
- Session 1 (replaced by this skill): explore the repo, interview the user to ~95% confidence about their actual intent, then author a requirements-style prompt.
- Session 2 (the actual deep researcher — ChatGPT-Pro by default): receives the emitted prompt (plus, remote-fetch, the uploaded manifest), explores and researches online as deeply as needed, and produces the deliverable directly — it does not re-interview.
The emitted brief is self-contained: Session 2 has none of this session's context, so everything it needs must live in the prompt plus the uploaded manifest (remote-fetch), the repository itself (local-session), or entirely inside the prompt (remote-fetch (inline) — an unfetchable repo).
Executor channels. ChatGPT-Pro is the default consumer (remote-fetch executor: uploads the manifest, fetches every file from a pinned commit). When the target names a local-session executor — another Claude/Claude Code session with direct repo read/write access — the same flow applies with the channel adaptations in references/brief-template.md §C: no manifest upload, live-tree instead of pinned-fetch semantics, and adjusted Step 6/7 handling. And when the repository is not fetchable by the executor — private without executor access, or otherwise unreachable — the remote-fetch channel degrades to remote-fetch (inline): the same no-repo-access consumer, but nothing can be fetched, so the brief itself carries everything (its §2 becomes the inlined material) and no manifest exists — references/brief-template.md §D owns those adaptations. "Session 2" throughout this skill means the executing session, whichever channel it is.
<HARD-GATE>
Do NOT Write the brief file or refresh the manifest until BOTH hold:
(a) confidence has reached ~95% — via the interview, OR via an early-exit — explicit ("just go") or implicit (user unavailable; Step 4 §Early exit) — with remaining gaps written into the brief as explicit, labeled assumptions, OR because scope arrived pre-settled from exploration alone (Step 4 §Interview-skip; carry any residual gaps as labeled assumptions); AND
(b) the Step 5 brief outline + settled-intentions summary has been presented in chat and the user has approved it (silence on a section while answering other questions counts as approval; an explicit objection re-opens that section and requires re-presenting the correction first). If the user is unavailable — a durable-unavailability signal mid-task, or an autonomous run where blocking is not an option (detection in Step 4 §Early exit — implicit; a bare `AskUserQuestion` timeout alone is transient, not durable) — (b) converts from a blocking request into a record: still present the outline in chat, proceed without approval, and flag every unapproved assumption prominently in the Step 7 summary so the user can correct it before using the brief.
The skill mutates only `reports/`. It NEVER edits `docs/`, `specs/`, `.claude/skills/`, or source code.
</HARD-GATE>Invocation
/research-brief "<what Session 2 should deep-research>" [reference_path]Step 1: Classify the research target
Silent setup before the first research-brief-owned user-facing output (or, on a direct invocation, the first user-facing output overall):
- Read
references/brief-template.mdin full. - Optionally run read-only baseline setup (
git rev-parse,git status,date) or path/tree listing, and read only the seed/reference file if one is explicitly provided. - Then emit the
Classification:line before any Step 2 repo-content exploration performed by this skill; on a chained invocation, apply the handoff boundary defined below.
The required template read anchors the rest of this step: §A is the canonical brief anatomy you author to in Step 6, and §B is the target-type→reads map you apply here.
Then read research_target (and reference_path in full if given). Classify into one type — this selects the load-bearing "read in full" set for Session 2 (the type→reads map is §B of references/brief-template.md):
- new-spec / new-feature — what to build/create next for the repo.
- thorny-fix — diagnose and resolve a stubborn defect or design knot.
- hardening — strengthen an existing system against drift, regression, or weak proof.
- foundational / doc-overhaul — overhaul a doc/design tier (or the cascade from an upstream change).
- other — anything else; build the read set from exploration alone.
Announce the classification on its own line as your first research-brief-owned user-facing output: emit Classification: <type> so the audit trail records it. On a direct invocation, this is the first user-facing output overall. On a chained invocation, outer-skill messages precede the handoff and do not violate this rule; emit the line as the first research-brief-owned output after the handoff. In both cases, read the template first and emit the line before any Step 2 repo-content exploration performed by research-brief. This Classification: line is also the skill-use announcement for this skill; do not emit a separate "using research-brief" message before the required template read. If an outer agent protocol requires announcing selected skills, satisfy it by adding one short clause to the Classification: line after the template read. (The template read is the prerequisite for classifying and is exempt. Read-only baseline git calls — git rev-parse, git status, date — are setup, not repo-content exploration, and may run before the line. Read-only path/tree listing for orientation — git ls-tree, find, glob — is likewise setup, not exploration; the gate is reading file contents, not enumerating paths. Repository-visibility / executor-access evidence calls required by the executor classification (e.g. gh repo view) are likewise setup, not exploration. Reading the seed/reference file itself — the positional reference_path or a file cited by path inside research_target — is also exempt.) When ambiguous, give a one-sentence justification.
A target may carry a dominant type plus a secondary (e.g. a hardening pass whose deliverable is a new spec). When so, classify by the dominant type to pick the primary read-set, union in the secondary type's load-bearing reads, and name both: Classification: <dominant> (secondary: <type>). When exploration later surfaces a secondary the first announcement could not have named, you may emit a single Classification refined: … line once, after the relevant Step 2 reads and before the Step 5 gate. Refine at most once.
Executor classification. Alongside the target type, classify the brief's consumer: remote-fetch (default — a ChatGPT-Pro deep-research session that uploads the manifest and fetches every file from a pinned commit) or local-session (the target names an executor with direct repo access — e.g. "you in another session", a Claude Code session on a named model). A third value splits remote-fetch by repository fetchability: remote-fetch (inline) — the consumer is still a no-repo-access deep-research session, but the repository is not fetchable (private without executor access, or otherwise unreachable), so the manifest is dead and the brief must be fully self-contained (references/brief-template.md §D). Determine it here from current repository visibility and executor-access evidence, not memory, a dated repository-state claim, or an upstream router's transport inference. When that evidence shows the repository is not fetchable by the executor, announce Classification: <type> (executor: remote-fetch (inline) — repo not fetchable). If the check is unavailable or inconclusive, raise repository fetchability as an explicit interview decision rather than applying a standing default. Announce a non-default executor on the Classification line: Classification: <type> (executor: local-session). When the target carries both a secondary type and a non-default executor, combine the two qualifiers in that order — type-refinement first, executor second: Classification: <dominant> (secondary: <type>) (executor: local-session). The executor selects the channel adaptations for the brief's anatomy (references/brief-template.md §C), the Step 6 manifest handling, and the Step 7 handoff wording; everything else — exploration, interview, gate, locked/no-questions — is channel-independent.
Step 2: Explore the repo to ground the brief
The point of authoring here is that Claude can read the repo directly — so the user never types out what the researcher should read. Build, from exploration:
- the authority-ordered read list. If the repo defines an explicit authority order among its docs, order §2 by it; otherwise infer a sensible root→detail order (README / overview → architecture / design → specs / roadmap → reference), then relevant
reports/,specs/,archive/. Each entry gets a one-line reason it is load-bearing for this target. - the relevant code seams Session 2 should inspect (name files/modules, don't paste them — Session 2 reads them itself);
- any prior report / spec / archived work that already bears on the target, so the brief frames the task as a delta rather than a cold start. When the target is a follow-up to an earlier brief, name the predecessor
reports/<...>-research-brief.mdexplicitly and state what it already delivered (seereferences/brief-template.md§1) so Session 2 does not re-commission completed work.
Launch Explore agents for broad surveys only when an Explore-agent equivalent is available and current tool/developer policy permits spawning it for this request. If no Explore-agent equivalent exists, or sub-agent policy requires explicit user permission and the user has not given it, use direct tree listings, search, and targeted reads instead; that fully satisfies this exploration step. Read individual files directly. Verify any repo claim in research_target or reference_path against the actual tree; flag contradictions prominently. Resolve a non-resolving path reference (a typo or near-miss filename — 13_ruels… for 13_rules…) to the intended file and state the correction; never fix it silently, since a silent resolution can land on the wrong file unnoticed. Expand every glob/wildcard reference in research_target (e.g. reports/foo-*) to concrete paths during exploration and state the expansion and its match count as an explicit line (e.g. reports/foo/* → 38 files; 12 primary, 26 boundary-awareness) — a displayed directory listing (git ls-tree output) is not that statement. The emitted brief's §2 read-in-full entries (primary and structural-model reads) carry only literal paths. A semantic / content selector — a filter phrased as content rather than a path wildcard (e.g. "all entries referring to X", "reports mentioning Y" over a directory) — expands the same way, but by a content grep rather than a path glob: run the grep, then state the matched paths and the match count exactly as for a literal glob. For a conditional selector — a user marks a wildcard, directory, or semantic selector as "maybe", "if needed", or consult-if-relevant — still expand it and state the match count, but do not automatically promote every match to the primary read-in-full list. Promote only concrete load-bearing files; place the rest under boundary-awareness / consult-as-needed with the conditional rationale. If exploration proves the whole tier is load-bearing, enumerate the literal paths and treat it as a whole-tier subject. A boundary-awareness tier may name a whole directory by path (e.g. reports/<trial-folder>/**) when the instruction is consult-as-needed and nothing in it is individually load-bearing; keep such directory globs out of the primary read-in-full list and under a clearly labeled boundary-awareness / consult-as-needed subheading.
Check that load-bearing inputs are tracked at the baseline — especially reference_path. A reference_path or §2 read that is untracked (freshly authored this session, or never committed — common when this brief is a chained hand-off from another skill) cannot be fetched by a remote-fetch executor, and its handling is not a mere write-time detail: it bears on the Step 1 executor classification (a local-session executor reads untracked files directly; remote-fetch must inline or commit) and is a genuine interview decision. When exploration — or the Step 1 baseline git status — shows a load-bearing input untracked, raise the choice (inline verbatim / commit-first and re-baseline / switch to a local-session executor) in the Step 4 interview, and let it inform the executor classification. (On remote-fetch (inline) the choice collapses — the channel inlines everything load-bearing by construction, so state the untracked status rather than interviewing it.) Step 6's untracked-input provision is then only the write-time mechanics of the choice already made.
Chained invocation inherits exploration. When research-brief is invoked as another skill's final phase (e.g. a sweep that has just read the whole tree), Step 1's classification-order rule begins at that handoff boundary; earlier outer-skill messages do not count against it. Inherit that exploration instead of repeating it — build the §2 read list from what was already read. You still owe the Step 5 path-resolution and §2-completeness checks against the baseline, which inherited context cannot substitute for.
Greenfield note. When exploration finds a near-empty tree and the read list would be near-empty, say so plainly in the brief and lean §5's exploration/online-research mandate harder — the brief then commissions design from first principles grounded in the repo's stated purpose (its README), not a delta over existing structure.
Step 3: Light online research (optional)
Only to sharpen scope and interview questions — surface the named techniques, prior art, or decision axes the interview should resolve. The deep research is Session 2's job; do not do it here. This line reports this session's scope-sharpening research only — never the brief's §5 Session-2 deep-research mandate, which every research-brief commissions; do not relabel that mandate as a Step-3 run. Because the deep research is delegated, for most runs the honest answer is skipped — Session 1 explores the repo, and online prior-art is Session 2's job; emit run only if you actually web-searched this session to sharpen the interview. Announce run-or-skip as a one-liner (e.g. "Online research: skipped — repo-internal; prior-art delegated to Session 2's §5 mandate" / "Online research: run — sharpening prior-art on tabletop game loops"). The research is optional; the run-or-skip announcement is not — emit it either way, as a peer of the Step 1 Classification: line.
The announcement is a binary run/skip committed at emit time, never a hedge. If you cannot commit at Step 3, emit nothing yet and defer the line until after exploration, then emit the committed line — but it must precede the Step 5 gate. ✗ "will decide after exploration" ✓ "skipped — repo-internal" / "run — sharpening prior art".
Step 4: Interview to ~95% confidence
Reach ~95% confidence about what the user actually wants — not what they think they should want — before drafting. Display this block after each answer. When sending a batched AskUserQuestion, emit the block immediately before the batch and again after the answers (the after-block is subsumed only when the answers reach threshold, in which case the "95% — drafting the brief" announcement replaces it) — and when the batch is in the same turn, fold the block's content into the first question's text, since same-turn prose may never render:
Confidence: X%
Gaps: [specific remaining unknowns]When the block precedes a batch in the same turn, its content must also reach a rendered surface — fold the confidence/gaps line into the batch's first question text, or emit the block in a prior visible turn — because same-turn prose beside an AskUserQuestion call may never render (canonical rendering rule: .claude/skills/grilling/references/questions.md §Rendering Rule).
Which path (pick before drafting): (a) Full discovery interview — scope is open; ask sequential/batched questions to 95%. (b) Tight bounded round — scope is largely pre-settled but residual decisions still materially shape the deliverable; pre-settle what is fixed and ask only those decisions as one AskUserQuestion batch. (c) Skip straight to the Step 5 gate — scope is fully pre-settled and no shaping decision remains. The Step 5 present-and-approve gate fires regardless of path. A blend is normal.
Rules: ask one conceptual question at a time when probing motivation or uncertainty sequentially, where each answer reshapes the next; but batch independent, already-scoped bounded choices into a single AskUserQuestion call (≤4 questions). A reshaping conceptual question may ride in a batch with bounded ones only when the bounded options stay valid across every plausible answer to it (with recommendations supplied); otherwise ask the reshaping question standalone first. Prefer bounded multiple-choice. Probe motivation before solution; challenge premature specificity; name uncertainty specifically; respect demonstrated expertise and "you decide" delegation (re-evaluate and recommend, don't re-ask). Confidence rises from both answers and exploration findings; note which gaps each closes. Do not bound a question on an unvalidated premise: when a bounded question's own framing rests on a fact that pending exploration would confirm or refute (not merely on the user's over-specificity), either wait for that exploration to ground it or pose the question in open form — offering fixed options on a shaky premise forces the user into a costly reframe rather than a clean selection. Between every two consecutive question rounds, re-display the Confidence / Gaps block first. Announce "95% — drafting the brief" when reached.
Mid-run scope injection. If the user volunteers a new requirement or scope change after the Classification line but before the Step 5 gate (a follow-up message adding a read, a concern, or a constraint), do not treat it as out-of-band: re-enter exploration for it, adjust the Confidence / Gaps block, and reconcile it into the Step 5 outline as a settled intention like any other — the gate is where the injected scope is confirmed, not a side-channel that bypasses it. A reshaping injection may reopen a Step 1 refine or a §2 read-list addition; carry any residual as a labeled assumption: if it arrives after the outline is already presented. A premise-correcting reframe can arrive inside an AskUserQuestion answer — the user rejects one batched question's framing instead of selecting an option (often via the "Other" field), while answering its sibling questions cleanly. Handle it by the same path: re-enter exploration for that dimension and reconcile it into the outline. The cleanly-answered sibling questions stay settled unless the reframe explicitly reopens them, and a Step 1 Classification refined: line fires only if the reframe actually changes the target type.
Comprehension/challenge question at the gate. Distinct from a scope injection (a new requirement) and from an objection (HARD-GATE (b), which re-presents the corrected section): after the Step 5 outline is presented but before approval, the user may ask a substantive understanding or challenge question about the brief's framing ("what is X about?", "how can Y be true if …?"). Answer it in chat; if the answer sharpens a settled intention or read (rather than changing scope), fold the refinement into the affected §3/§2 item, note in one line that you did, and re-offer approval — do not re-present the whole outline unless a settled intention actually changed.
Early exit — explicit: if the user says "just go," announce current confidence by re-displaying the Confidence / Gaps block one final time, and carry the remaining gaps into the brief as labeled assumptions (assumption: X) so Session 2 — which will not ask — treats them as decisions the user can later correct.
Early exit — implicit (user unavailable): convert the gate to autonomous — adopting your own recommended answers, whether or not an AskUserQuestion attempt was burned first — only when the harness context signals durable unavailability mid-task: an operating-autonomously system reminder ("the user is not watching in real time"), a headless/cron/scheduled invocation, or an explicit "just produce it, don't ask" instruction in the target itself. Recognizing one of these signals is a rule application, not a judgment call. A bare AskUserQuestion timeout is not, by itself, a durable signal — a 60-second no-response is usually a transient away-from-keyboard (the harness itself invites re-asking the question later), so holding for the user's return, or re-issuing the batch when they return or direct it, is sanctioned, not forbidden; convert to autonomous only if a durable signal above is also present, or the timeout recurs with no sign the user will return. A batch re-issued after a transient away gets the same pre-batch Confidence / Gaps block as an initial send (this step's batch cadence). When you do convert for real: adopt your recommended answers, convert every unresolved gap and adopted recommendation into labeled assumption: lines, re-display the Confidence / Gaps block one final time, and proceed to Step 5 — where the outline is presented as record rather than as a blocking request (HARD-GATE (b)). Flag the unapproved assumptions prominently in the Step 7 summary so the user can correct them before using the brief.
Interview-skip (exploration-settled). When exploration alone brings confidence to ≥95% before any question, skip the discovery interview: announce the confidence level on its own line (e.g. Confidence: 95% — drafting the brief), carry any residual gaps as labeled assumptions, and proceed straight to the Step 5 outline gate. Re-confirm only a gap that materially changes the deliverable's shape, and do so inside the Step 5 outline. The Step 5 present-and-approve gate still fires and remains the real checkpoint; skipping the interview never skips it. On an autonomous run this path composes with §Early exit — implicit: the one-line confidence announcement satisfies that section's final Confidence / Gaps block re-display, and the Step 5 gate follows §Early exit — implicit's handling (presented as record, per HARD-GATE (b)).
Step 5: Present the brief outline (HARD-GATE)
Before writing, present in chat:
- the settled intentions — the resolved decisions the interview produced (these become §3 of the brief and are what make Session 2 "locked");
- the assumptions / residual gaps that will be carried into the brief as labeled
assumption:lines, or "none"; - the deliverable spec — exactly which downloadable markdown docs Session 2 must produce (replace vs. new, filenames); for determination-plus-conditional targets ("decide if X is needed, and if so produce X"), state both the required verdict and which of the three production modes governs the artifact (see
references/brief-template.md§7); - the local files this session will write on approval — the inferred
reports/<topic>-research-brief.mdpath, plus the remote-fetch manifest path pattern (reports/manifest_<today>_<shortsha>.txt) — or, for local-session and remote-fetch (inline), that no manifest will be written (inline: the channel has none; local-session: unless the user asked for one); - the read-in-full list (authority-ordered, with the one-line reasons). Large-package economy: when the read list is large, you need not enumerate every entry with its reason in chat — present it by authority tier + the flagged/priority targets + the boundary-awareness group (reasons stated once per group), and defer the full per-file one-line reasons to the written §2. Full enumeration stays the default for small lists. When the read list is a whole doc tier (an overhaul where every file is load-bearing), the written §2 uses the tier-enumeration-plus-hot-spots-map form rather than a per-file reason list — see
references/brief-template.md§2's whole-tier-subject note.
Before presenting, confirm both audit-trail announcements were emitted earlier this run: the Step 1 Classification: line and the Step 3 online-research run-or-skip one-liner. If either was missed, emit it now. Also confirm the target type the outline (and the brief's §4) will carry — including any secondary — matches the announced Classification line; if it does not, emit the Classification refined: line first, per Step 1's refine-once rule. Also confirm every glob or semantic/content selector in research_target was expanded with its match count stated as an explicit line (Step 2) — a directory listing shown during exploration does not count as the statement; if an expansion went unstated, state it now. Also confirm every path in the read-in-full list resolves in the executor's channel — remote-fetch: at the fetch-baseline commit (git ls-tree <baseline> <path> / git cat-file -e <baseline>:<path>), so the list you present is the list Session 2 can actually fetch; local-session: in the live working tree, explicitly marking any untracked entry or working-tree divergence from the authored-against baseline (per references/brief-template.md §C); remote-fetch (inline): there is no fetch list — confirm instead that every load-bearing input is carried inside the brief (the inline-completeness check) and that any repo path the brief mentions is marked provenance-only. A single batch check satisfies this — one full-tree listing (git ls-tree -r --name-only <baseline>, run from the repo root — the command is CWD-relative; see Step 6 item 2) or a set-difference against the §2 list — provided it covers every entry; the per-path commands remain the fallback for spot checks. Drop or correct any path that doesn't resolve. Boundary-awareness entries that are literal file paths get the same resolution check; a directory glob (e.g. reports/<trial-folder>/**) needs only its directory to exist.
Carry-forward check. When a seed or predecessor report pins a different commit than the fetch baseline and you carry any of its findings forward (seam maps, file:line citations, descriptive claims), verify the carry-forward against the baseline before the outline presentation asserts it — the outline carries the claim, so the diff runs first. Run git diff --stat <seed-commit> <baseline> -- <the §2 seam paths> and scope every carried claim to the files that diff confirms unchanged. Path-scope the diff so that an empty result is itself the proof — never conclude "unchanged" by inference over an unscoped listing — and do not truncate or pipe a verification command's output through head/tail (a scoped diff is already small, so output discipline is satisfied without hiding hits). Never assert "the predecessor's findings still hold" from memory; an empty diff is the clean result to state plainly, a non-empty one scopes the claim.
High-level lineage summaries — e.g. naming a predecessor report and summarizing what that report delivered in its own historical context — do not by themselves trigger the carry-forward diff. The diff is required when the outline makes a current assertion that predecessor findings, seam maps, file:line citations, or descriptive claims still hold at the new baseline.
The inverse case — a §2 evidence input at an older baseline whose findings intervening revisions may have overtaken — is handled in references/brief-template.md §1 (the stale-evidence-input provision): flag the divergence, and carry a §3 settled intention telling Session 2 to re-verify that input's findings against the current tree and label each (survives / overtaken / partly-addressed) rather than assume they still bind. This fires even when the primary adjudication input is current (at the fetch baseline) but a secondary evidence input it relies on is stale — see §1's mixed-staleness note.
Get approval (per the HARD-GATE). Revise on pushback before writing. On an implicit early exit (user unavailable), the presentation stands as record and the run proceeds without approval — per HARD-GATE (b).
Step 6: Write the brief and refresh the manifest
On approval (or on an implicit early exit, after presenting the outline as record), first run the post-approval preflight, then do BOTH — except that a local-session executor skips item 2 by default (see the local-session note below), and a remote-fetch (inline) run skips item 2 always — an unfetchable repo gives the manifest no consumer (see the inline note below):
Post-approval preflight. If approval arrives in a later user turn after the Step 5 outline, re-check the baseline before writing: run git rev-parse HEAD, git status --short, and date +%F. If HEAD changed, if §2-relevant paths are dirty, or if the prior §2-completeness check no longer covers the current baseline, re-run the §2-completeness check and adjust the brief/manifest baseline before writing. If only unrelated working-tree dirt appeared, leave it alone and surface it in Step 7 per the dirty-tree rule. Re-sample date +%F here — never reuse the value from the Step 1 baseline setup: a session that crosses a date boundary between outline and write would otherwise misdate the manifest filename's <today> (item 2), whose date must reflect when the inventory is actually generated.
- Write the brief to
reports/<topic>-research-brief.md, following the canonical anatomy inreferences/brief-template.md§A (read in Step 1).<topic>is a short kebab-case slug of the target. Mind the one-word gap from the deliverable: the brief you write now is<topic>-research-brief.md, while the §7 deliverable Session 2 writes is often<topic>-research-report.md(same slug,briefvs.report). Do not conflate them when choosing the file path you Write, the §1 manifest pointer, or §7. Createreports/if it does not exist. - Refresh the manifest: write the current repository path inventory to
reports/manifest_<today>_<shortsha>.txt, where<today>is the real current date (date +%F),<shortsha>is the fetch-baseline commit's short hash (git rev-parse --short HEAD), and the inventory is that exact commit's tree —git ls-tree -r --name-only HEAD(use the same<baseline>you pin in the brief's §1, notgit ls-files, so the manifest provably equals the commit Session 2 fetches from). Generate it anchored to the repo root —git -C <repo-root> ls-tree -r --name-only <baseline>with an absolute output path — becausegit ls-tree -r --name-only HEADis CWD-relative: run from a subdirectory (e.g. after an earliercdthat persisted across Bash calls) it silently lists only that prefix's subtree and ships a truncated manifest that breaks Session 2's fetch. Then sanity-check completeness before trusting it — confirm the entry count is repo-wide (matchesgit -C <repo-root> ls-tree -r --name-only <baseline> | wc -land includes a known top-level path), not a subtree. If a Bash redirect is blocked or misfires, capture thels-treeoutput and Write it to the absolute path instead. Name this exact file in the brief's §1 manifest pointer so Session 2 uploads the matching inventory. Leave older manifests in place for the user to clean; regenerate only when one already exists for this exact<today>_<shortsha>.
Local-session executor: no upload bundle. A local-session executor reads the repository directly, so the manifest has no consumer — skip the refresh by default and write only the brief; generate a manifest only if the user asks for a baseline snapshot. The brief's §1 then pins the baseline as the authored-against commit (with a verify-HEAD / work-from-live-tree instruction), not a fetch-from commit — see references/brief-template.md §C. The §2-completeness check below still applies (a dangling §2 path is broken in any channel); the fetch-oriented clauses of the baseline-commit rule apply only to remote-fetch.
Remote-fetch (inline): no upload bundle either. An unfetchable repo gives the manifest no consumer — write only the brief. Its §1 carries the authored-against commit as repo-side provenance outside the paste payload (never a fetch-from instruction), and §2 becomes the inlined material per references/brief-template.md §D. The §2-completeness check becomes an inline-completeness check: every load-bearing input travels inside the brief — verbatim or as the sanitized restatement §D's interview item settles — and no path is referenced for the executor to read. The fetch-oriented clauses of the baseline-commit rule below do not apply.
Baseline-commit rule (remote-fetch). The brief instructs Session 2 to fetch every file from one exact commit, so the manifest must list exactly that commit's tree. Derive the fetch-baseline commit from verified repo HEAD (git rev-parse HEAD) at manifest-refresh time, and generate the manifest from that same commit (git ls-tree -r --name-only HEAD) — do NOT use git ls-files, which reflects the staged index and silently diverges from HEAD under any uncommitted add/delete/rename. This command is also CWD-relative: run from a subdirectory it lists only that directory's subtree, so anchor it to the repo root and verify the manifest is repo-wide, never a subtree (the how-to and completeness check live in item 2 above). If you do fall back to git ls-files, first confirm git status --porcelain is clean (or reconcile every listed delta) and note the check in the Step 7 summary. NEVER adopt a commit string copied from a report, doc, or research_target without confirming it contains every file in the §2 read-in-full list (git ls-tree <commit> <path> / git cat-file -e <commit>:<path>) — a "commit of record" cited inside a report is that report's own baseline and often predates later work. If a referenced source cites a different commit, call out the divergence inside the brief rather than propagating it.
§2-completeness check. Confirm every file in the §2 read-in-full list — including files discovered transitively, e.g. a predecessor report's own cross-references — actually exists at the baseline before presenting the list (Step 5) and before writing. A path present in your working tree but absent at the baseline (never committed, or cleaned up in an earlier commit) would ship as a dangling §2 reference and break Session 2's fetch — self-containment is the contract. Drop or correct any that do not resolve, and flag the contradiction. Untracked load-bearing input (remote-fetch; §C relaxes this for local-session): a §2 path that is untracked (?? in git status, fails git cat-file -e HEAD:<path>) cannot be fetched from the baseline. Do not reflexively drop it: if the whole file is load-bearing (e.g. the seed the brief triages), reproduce it verbatim inline in the brief (an appendix) so it travels with the pasted prompt, and note in §1/§2 that it is inlined-because-untracked. If only a bounded excerpt is load-bearing (e.g. a sibling brief's scope boundary), inline that exact excerpt, state that the full file is not incorporated, and explain the excerpt's role. If it is non-essential, drop it or ask the user to commit it and re-baseline.
Post-write coherence check. After Writing the brief, re-read it once and confirm it renders cleanly as the paste-ready artifact Session 2 consumes verbatim: balanced code fences (none left open or accidentally doubled), section anchors and cross-references that resolve, and no leftover authoring markup. A malformed fence or dangling section ships straight into the pasted prompt. For a freshly-authored brief a targeted structural check satisfies this — grep for even code-fence-line parity and the expected ## N. section headers, plus a grep of any internal cross-references — as an alternative to a full re-read; fall back to the full re-read when the brief inlines large untracked content (an appendix) or is unusually long. For a local-session brief, this check also verifies that every untracked or working-tree-divergent §2 path satisfies Brief template §C — Local-session executor adaptations, which owns the exact-label rule.
Resolve both paths against the worktree root if in a worktree. Do NOT commit.
Repeat-run brief already at the target path. When reports/<topic>-research-brief.md already exists from an earlier run or session, you must Read the existing file before writing — the Write validator rejects an unread overwrite. Read it, then overwrite; note the overwritten predecessor's lineage in §1 (see references/brief-template.md §1).
Re-baseline an existing brief (HEAD moved). When a brief must be re-issued only because HEAD has since changed (the user committed, merged, or pushed) and the settled intentions still hold, do not re-run the Step 1–4 interview; reuse the intentions verbatim. Instead: (a) regenerate the manifest at the new HEAD (new <shortsha> → new filename, so it never overwrites the old one); (b) replace every commit string in the brief's §1, §7, and §8 with the new baseline; (c) re-resolve every §2 path against the new baseline (a committed rename may have relocated files; a previously-untracked inlined input may now be fetchable — add it as a normal §2 read); (d) re-run the §2-completeness check and grep the brief for the stale shortsha; (e) leave the superseded manifest in place. If the intentions have changed at all, this shortcut does not apply — run the normal Step 1–4 flow. Local-session reading: skip (a) and (e) (there is no manifest); the sequence reduces to updating the §1 authored-against pin (plus any other commit strings, per (b)) and re-running (c)/(d)'s path checks — and it fires only when the moved HEAD changes §2-relevant content, since Session 2's verify-HEAD instruction already absorbs an unrelated move by noting the divergence.
Step 7: Summarize
Report every numbered item below (items 2 and 6 are conditional as stated; the rest are unconditional) — check each off individually before ending the turn:
Use this closeout checklist before the final response. If an item has no content, write none rather than omitting it:
Written files:<brief path + manifest path, or brief path only for local-session and remote-fetch (inline)>Leftover manifests:<this brief's upload manifest and which prior/sibling/legacy manifests must not be uploaded; or none>Locked/no-questions reminder:<remote-fetch paste/upload/direct-deliver reminder, remote-fetch (inline) paste-only reminder (upload nothing), or local-session handoff reminder>Early-exit assumptions:none /<labeled assumptions and approval-status warning if implicit early exit fired>Benign dirty note:<the new/modified reports files are benign and do not invalidate the baseline>Other dirt:none / <unrelated or load-bearing dirty paths, with channel-specific consequence>
- The written files. Remote-fetch (fetchable): brief + refreshed manifest, the upload bundle for ChatGPT-Pro Session 2; local-session and remote-fetch (inline): the brief alone.
- Leftover manifests (all channels — the wrong-upload hazard is a remote-fetch one). Name any leftover manifest — at this or any earlier baseline, whatever slug or run produced it — stating which brief it pairs with (or that it pairs with none): one from this slug's own earlier remote-fetch run is now-orphaned; one from a sibling brief's remote-fetch run is not part of this brief's channel and should not be uploaded alongside the new brief. Determine the pairing by matching the manifest's
<shortsha>to a brief's §1 fetch-baseline declaration (the "Fetch every file from commit<HEAD>" line a remote-fetch brief pins) — not a bare grep for the shortsha anywhere in the file: a brief legitimately cites foreign commits in its §1 prose (a predecessor's baseline, a report's commit-of-record), so a bare shortsha grep false-positives, pairing a manifest with a brief that only mentions that commit historically. Pair by the fetch-baseline pin, not by any shortsha occurrence. This scales down when many manifests have accumulated: identify this brief's manifest (the one whose<shortsha>matches §1's baseline) and state that the rest are prior or sibling briefs' and must not be uploaded — grep-pair an individual manifest only where its provenance is genuinely ambiguous, not all of them by rote. A pre-convention manifest with no_<shortsha>component (e.g.manifest_<date>.txtfrom before this naming rule) cannot be classified by the shortsha grep — flag it by name as a legacy artifact rather than forcing a pairing. In a remote-fetch run especially, spend the one line: with several manifests now inreports/, naming which file is this brief's manifest — and that the others must not be uploaded with it — forecloses a stale-manifest upload, the very failure the pinned-baseline contract exists to prevent. The user can clean or keep any of them deliberately. An inline-channel brief pairs with no manifest at all — say so explicitly, and that none of the accumulated manifests may be uploaded with it. - The locked / no-questions reminder, one line — remote-fetch (fetchable): paste the brief, upload the manifest, and ChatGPT-Pro should produce the deliverable directly; remote-fetch (inline): paste the brief's payload (from its stated paste boundary down) and upload nothing; local-session: start a fresh session and point it at the brief file.
- Early-exit assumptions. Any labeled assumptions carried from an early exit, so the user can correct them before handing off — and, on an implicit early exit, a prominent flag that the outline was presented as record only and never approved.
- The benign-dirty note. State that the
reports/files you just wrote leavegit statusdirty (one or two new/modifiedreports/files — the brief is untracked on a first run but shows as modified when a repeat run overwrites an existing brief at the same slug) and that this is benign — it does not invalidate the §1 baseline. (Rationale for the note's wording — remote-fetch: the manifest isgit ls-tree HEAD, which excludes untracked files, so it still equals the pinned commit. Local-session and remote-fetch (inline): there is no manifest, and the §1 pin is an authored-against commit — one untracked or modified brief does not move it. In every channel, only a later commit/merge/push that moves HEAD affects the baseline — consequences in item 6.) - Other dirt, if present. If
git statusis otherwise dirty at write time — pending moves/renames affecting §2 paths, an untracked load-bearing input reproduced inline, or any other uncommitted change — proactively warn the user what committing (or merging/pushing) that dirt does in this brief's channel — remote-fetch: it does not break the brief — Session 2 fetches from the pinned commit SHA, which persists in the object store and stays fetchable after HEAD moves, and the manifest still equals that commit's tree; the only consequence is that the brief now reflects the pre-commit tree, so the re-baseline sequence in Step 6 is needed only if the user wants the brief to reflect the new HEAD (or the commit relocated/removed a §2 path, or orphaned the pinned commit — the genuine break cases); local-session: the §1 pin is authored-against provenance, so the brief survives — Session 2's verify-HEAD instruction absorbs the move by noting the divergence, and the re-baseline sequence's local-session reading applies only if the commit changes §2-relevant content; remote-fetch (inline): the brief is self-contained, so a moved HEAD changes nothing for the executor — only the repo-side provenance pin goes historical.
Conditional report items pushed in from other sections land here too when they fired: the git ls-files fallback check (Step 6 baseline-commit rule) and any degraded-tooling substitution (Guardrails).
This is an inline-completion deliverable — no next-steps menu. Surface any adjacent improvement spotted during exploration as a flagged note with a concrete trigger, not as scope creep.
Guardrails
- Self-containment is the contract. Session 2 has none of this session's context. Every path, decision, constraint, and acceptance check it needs lives in the brief plus the uploaded manifest (remote-fetch), the repository itself (local-session), or the brief alone (remote-fetch (inline)) — never implied.
- This session authors; Session 2 researches. Don't perform the deep research here. The brief commissions it — whichever executor channel consumes it.
- Locked, no questions. The emitted brief instructs Session 2 to produce directly and NOT interview or ask clarifying questions — the interview already happened here.
- Mutates only
reports/. Never touchdocs/,specs/,.claude/skills/, or source. - No scope inflation. The brief commissions what was asked. Resist "while we're at it" additions to the deliverable spec.
- Ground constraints in this repo, not a template. Derive §6 doctrine & constraints from what exploration actually finds (this repo's own authority docs, invariants, conventions) — do not import constraints from another project. Recalled project memory counts as a repo-grounded source: fold any memory that constrains the target (standing limitations, scope exclusions, adjudication standards, named-tool reliability) into §3/§6 per
references/brief-template.md§6, not only the tool-reliability case. - Degraded tooling. When command execution is unavailable mid-run (tool outage, denied permission), equivalent read-only evidence may substitute for a mandated command — e.g. reading
.git/HEAD/.git/refs/heads/<branch>for the baseline pin, or a verified-current status snapshot for tree cleanliness — provided the substitution and its evidence are recorded in the Step 7 summary. A check with no genuine equivalent (the Step 5 carry-forward diff especially) must be retried before Step 6 or carried into the brief as a labeledassumption:.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

