research-piece
Research a writing Piece's Supporting Material: download its PDFs, have one sub-agent per source read its listed passages, verify every quote against the text, check every fact with /review-research,
SKILL.md.claude/skills/research-piece/SKILL.md
GitHub/research-piece <repo> <n> researches the Research issue <repo>#<n>. Its output is a verified fact list posted as a comment on the issue; it writes nothing to the Deliverable and has no branch. The spec's body changes only through npm run outline:apply, by an edit the developer approves.
Fetch the issue with npm run issue:read -- <repo> <n> --body and state its title before starting. If the reference is ambiguous, ask. If the issue is a Piece rather than Research, stop and point the developer to /implement-piece.
Work at the primary root or in a session workspace. Research edits no files in a repo, so no issue workspace is needed. Scratch files go in the scratchpad.
Steps 1–7: both modes
An interactive session and the runner's research step both follow steps 1–7, /review-research pass and acting on its verdicts included. A runner's research step stops after step 7, before posting: it posts nothing and deletes nothing, and leaves comment.md and the texts folder in its scratch folder for the runner to read.
- Read the sources the spec lists. Every source is a Drive file, one source per ID;
/grill-piecesaved each web page to Drive, and this skill never reads one live. Each source's text goes in<scratchpad>/texts, under a short file name such asheagney.txt, the name its locators will cite. For a short text, read it withget_drive_file_contentand save what it returns there. For a PDF, download it withget_drive_file_download_url, then dump its text once perdocs/pdf-pages.md:npm run pdf:text -- "<path>" "<scratchpad>/texts/<name>.txt". Its page markers are what locators cite. - Give each source to one sub-agent, a
general-purposeagent onsonnet. Each reads only its own text file and the passages the spec lists, and returns facts in its own words, each ending with its locator:(<name>.txt, PDF pp. 45–46 (printed 31–32)), or(<name>.txt, PDF p. 45)for one page, with the printed pages only when they differ; for a source with no page markers,(<name>.txt, heading "<the heading it sits under>"). A quote is optional, added when the wording matters or to anchor the spot. Each quoted passage is copied word for word from the text, punctuation included, never paraphrased. A quote is one contiguous passage: never join two passages with..., and quote each one separately. A term or title that isn't a quote goes in italics, never double quotes. Each agent gets the text file's full path, its file name for the locator and the list of passages to read. - Assemble the fact list in the scratchpad as
comment.md: one numbered fact per line, each in the researcher's words and ending with its locator in the shape above, each quoted passage in double quotes. - Verify the quotes.
verify:quoteschecks that every fact has a locator and every double-quoted span is found within its cited range; it doesn't judge whether a fact is right, and it isn't the plagiarism check. Runnpm run verify:quotes -- --comment "<scratchpad>/comment.md" --texts "<scratchpad>/texts". Fix everyNOT FOUNDby copying the passage exactly from the text, or remove the quote. Fix everyOUTSIDE LOCATORby correcting the locator to where the quote is, when the fact comes from there. Fix everyNO LOCATORby adding or correcting the fact's locator. Fix everyJOINEDby splitting it into one quote per passage. Rerun until it exits 0. Punctuation and wording must match exactly; letter case and line breaks may differ. - Review the draft. Read
.claude/skills/review-research/SKILL.mdand follow it oncomment.mdand the texts folder; it is user-invoked, so the Skill tool can't reach it. One pass: the draft is not reviewed again after the next step. - Act on its verdicts once. Leave each supported fact as it is. Rewrite each partly supported fact from the reviewer's quote and location, in your own words. Move each unsupported or unverified fact to a
## Unverifiedsection at the end ofcomment.md, with what was looked for and the reviewer's reason.## Unverifiedis outside the fact list: nothing is drafted from it. - Verify the quotes again, by step 4's command and fixes, until it exits 0. A runner's research step stops here.
Steps 8–12: an interactive session only
- Post the comment with
gh issue comment -R <owner>/<repo> <n> --body-file "<scratchpad>/comment.md", resolving<repo>to<owner>/<repo>. - Put what's left to the developer, in one message, as a run's Research Halt would: each wanted fact, an
## Unverifieditem whose fact the issue's## Factsfield names, numberedF1on; and each Outline edit the research calls for, numberedE1on, as its section, the old text quoted exactly from the spec's## Outline, the new text and the reason. The spec is the issue's parent. The answers aredrop F<n>,another source F<n>naming the source, andapprove E<n>. With nothing to put, go to step 12. - Settle an
another sourceanswer by/runner's step 6, with no Halt to answer: one fact from one Drive file gets an addendum comment; anything larger is the developer's Research ticket. - Apply each approved Outline edit through the runner's code, never by editing the spec body yourself; with no
approve E<n>in the reply, go to step 12. Write every proposed edit, inE<n>order, to<scratchpad>/edits.jsonas a JSON list of{ "section", "oldText", "newText", "reason" }, then runnpm run outline:apply -- <repo> <spec n> --edits "<scratchpad>/edits.json" --answer "<the developer's reply, word for word>". It applies only the edits the reply approves, word for word. When it names an edit it couldn't apply, tell the developer to make that change by hand. - Delete the downloads:
rmeach path thatget_drive_file_download_urlreturned.
Done when
An interactive session is done when every fact in the posted comment's fact list has a source and a page range, or a heading for a source with no pages, and /review-research found it supported or it was rewritten from the reviewer's quote; every other fact is under ## Unverified; verify:quotes exits 0 on the posted file; the developer has answered each wanted fact and proposed edit; and the downloads are deleted.
Wrap-up
Then run npm run wrap-up -- <repo> <n> --no-code; nothing is committed, pushed or closed before it.