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

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.

  1. Read the sources the spec lists. Every source is a Drive file, one source per ID; /grill-piece saved 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 as heagney.txt, the name its locators will cite. For a short text, read it with get_drive_file_content and save what it returns there. For a PDF, download it with get_drive_file_download_url, then dump its text once per docs/pdf-pages.md: npm run pdf:text -- "<path>" "<scratchpad>/texts/<name>.txt". Its page markers are what locators cite.
  2. Give each source to one sub-agent, a general-purpose agent on sonnet. 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.
  3. 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.
  4. Verify the quotes. verify:quotes checks 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. Run npm run verify:quotes -- --comment "<scratchpad>/comment.md" --texts "<scratchpad>/texts". Fix every NOT FOUND by copying the passage exactly from the text, or remove the quote. Fix every OUTSIDE LOCATOR by correcting the locator to where the quote is, when the fact comes from there. Fix every NO LOCATOR by adding or correcting the fact's locator. Fix every JOINED by 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.
  5. Review the draft. Read .claude/skills/review-research/SKILL.md and follow it on comment.md and 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.
  6. 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 ## Unverified section at the end of comment.md, with what was looked for and the reviewer's reason. ## Unverified is outside the fact list: nothing is drafted from it.
  7. 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

  1. Post the comment with gh issue comment -R <owner>/<repo> <n> --body-file "<scratchpad>/comment.md", resolving <repo> to <owner>/<repo>.
  2. Put what's left to the developer, in one message, as a run's Research Halt would: each wanted fact, an ## Unverified item whose fact the issue's ## Facts field names, numbered F1 on; and each Outline edit the research calls for, numbered E1 on, 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 are drop F<n>, another source F<n> naming the source, and approve E<n>. With nothing to put, go to step 12.
  3. Settle an another source answer 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.
  4. 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, in E<n> order, to <scratchpad>/edits.json as a JSON list of { "section", "oldText", "newText", "reason" }, then run npm 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.
  5. Delete the downloads: rm each path that get_drive_file_download_url returned.

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.