Feedback Triage

Feedback Triage

Overview

Process alpha/beta reader feedback as a structured, reconcilable workflow: collect per-reader feedback files, hold all revision until the round is complete, synthesize convergent/divergent/single-reader findings into a decision record with a readiness verdict, and hand a concrete revision plan to the revision-continuity skill.

Prerequisites

A story project with at least one drafted chapter (or a complete draft) that readers have read. Verify story.md exists in the project root.

When to Use

• Starting a feedback round (recruiting readers, sending chapters out)
• Giving readers a review copy, including the GitHub Pages review-copy workflow and the reader-note issue form (step 1 of the workflow; other skills point here)
• Recording feedback as it arrives
• Synthesizing a completed round into decisions
• NOT for revising the manuscript (use revision-continuity with the synthesis's revision plan)
• NOT for the agent's own critique of the draft (use revision-continuity audits; reader feedback is external input)
• NOT for producing simulated persona reads (use reader-panel; this skill synthesises the round it writes)

Workflow

1. Set up the round

1. Decide the round scope: which chapters readers get (chapters-read range) and how many readers (2–4 per round is typical; one reader is a data point, not a round).

2. Create the round folder: feedback/round-{N}/.

3. Give readers a review copy they can open without a terminal. Build it from text you can get back, so the round can be rebuilt and old labels mapped later (step 2 of Collect). Save that text first:

   • Git project: work from the book's folder, the one that holds story.md (cd there first), because -- . below means the current folder. Check that .gitignore lists dist/ (story init writes one that does; add the line if it is missing), so earlier review copies stay out of the commit. Then run git status --untracked-files=all -- . and show the user what it lists: the copy is built from the working tree, but a tag points at the last commit, so uncommitted changes would make the two differ. Look through it for private files (a .env, keys or credentials, scanned documents): unless the user says to commit one, add it to .gitignore first. Ask before committing and before tagging. With approval, commit the project folder only (skip the commit when the tree is already clean) and tag that commit:

     git add -A -- .
     git commit -m "Feedback round {N}" -- .
     git tag feedback-round-{N}

     If the user declines the commit, never tag the last commit over an uncommitted tree: take a snapshot as below, or stop.

   • Project without git, or the user declined the commit: take a snapshot with story snapshot feedback-round-{N} --path ..

   Then build the stamped HTML copy from that text:

   story build . --format html --stamp feedback-round-{N}

   Never push, and never move or delete a tag, without the user's approval: a push to main can publish the manuscript through the review-copy workflow below. The single-file HTML copy in dist/ has a table of contents, the build stamp at the top, and a paragraph label beside every paragraph (ch03-p12 is chapter 3, paragraph 12). A label is the chapter and the paragraph's position in that build, not a permanent id: any earlier edit in the chapter renumbers it, and story move changes its chapter part. Ask readers to cite the label, the build stamp, and the paragraph's first few words with each note.

   GitHub review copy. This is the setup the other skills point to. For a project on GitHub, offer the templates from the Story Skills repository (https://github.com/danjdewhurst/story-skills, templates/github/). The review-copy.yml workflow publishes the HTML copy to GitHub Pages on each push to main, stamped with the date and short commit, with a Note link beside every label (--note-url) that opens the issue form prefilled with the label, build, and first words. Like every build, it leaves out a matter page whose permission is pending or unclear (warning permission-pending-left-out), so an uncleared epigraph never reaches Pages; never add --include-pending to the workflow. The ISSUE_TEMPLATE/manuscript-note.yml issue form asks readers for the label, build, first few words, note type (typo or wording, confusing, continuity, pacing, character, sensitivity or authenticity, loved this, other), how much it affected their reading, and the note. Before asking to copy them, warn that a public Pages site makes the manuscript public unless the repository and Pages are private, and confirm the visibility the user wants. Then copy them into the story repository's .github/workflows/ and .github/ISSUE_TEMPLATE/ only with the user's approval, and create a manuscript-note label first; GitHub only applies existing labels.

4. For each expected reader, create a stub file from references/feedback-template.md at feedback/round-{N}/{reader-kebab}.md with frontmatter filled in and the body sections empty. The stub list is the round's checklist.

2. Collect feedback (the discipline)

1. As each reader's notes arrive, record them in their file using the template. Quote or closely paraphrase; do not editorialize yet. Keep each note's paragraph anchor (ch03-p12) in its Where line; convert chapter or page references from other formats to anchors when the location is unambiguous. For notes filed through the issue form, fetch them with gh issue list --label manuscript-note --state open --json number,title,body,author and map the form's "How much did it affect your reading?" answer to the template's severity: Made me want to stop reading is major (blocking when several readers stopped at the same place), Pulled me out for a moment is minor, Barely noticed is nit, and a blank answer is minor. A Typo or wording note with a blank answer is a nit unless the reader says more.

2. Map old labels to the current text. When a note's build is older than the manuscript, its label may point at a different paragraph now. Resolve every label from the round in one run against the text the round saved in step 1: the git tag (or the short commit in the note's build stamp), or the snapshot of the same name when the project has no git or the user declined the commit. A reader-panel round saved its text the same way as panel-round-{N} instead of feedback-round-{N}. git tag --list 'feedback-round-{N}' and story snapshot --list --path . show which one the round has. Readers type labels into the issue form, so before a label goes into the command, check that it is lower-case letters, digits, and hyphens ending in -p and a number (ch03-p12, front-epigraph-p1), and ask about any other. Quote each label:

   story compare . --ref feedback-round-{N} --anchor 'ch03-p12' --anchor 'ch07-p4'

   For a snapshot, use --snapshot feedback-round-{N} in place of --ref. Each line gives the current label: (text unchanged), or (edited, NN% similar) when the paragraph was revised (check it is the one the reader meant). not found in the current text ("…") means the paragraph was cut or rewritten past recognition: search the chapter for the reader's quoted words, or the words shown, and mark the note ambiguous if nothing matches. no such label means the label never existed in that build: check the note's build and the reader's typing. Record the current label in the Where line, keeping the reader's original label in brackets. Sensitivity and authenticity reads use the same file shape; see the editorial-review skill for commissioning them.

3. Run the canon check on each problem note: verified against the bible, contradicts canon (usually a setup problem — note the canon file), or outside canon scope. Record the result in the file.

4. Do NOT revise until all feedback for the round is in. Revising on partial feedback optimizes for the first reader and invalidates the others' reads. If a reader is late, either wait or formally close the round without them (note it in the synthesis) — never silently proceed on a partial set.