triage-feedback

Files (7)

• SKILL.md
• apply.py · dashboard/
• build.py · dashboard/
• decisions.py · dashboard/
• review.py · dashboard/
• serve.py · dashboard/
• template.html · dashboard/

SKILL.md (first lines)

# Triage feedback

The dashboard turns a batch of feedback into a page where the user approves or rejects each
proposed fix. Each card shows the problem, its evidence, the case against changing it, the
affected lines in context, and the exact replacement. The scripts in this skill's `dashboard/`
folder need only Python 3 and Git; posting a review also needs `gh`.

| Script | Does |
|---|---|
| `build.py RUN/findings.json [--check]` | Checks every finding against the files and writes `index.html` and `resolved.json` |
| `serve.py start RUN` / `stop RUN` | Serves the page on localhost and saves decisions to `RUN/decisions.json` |
| `apply.py RUN [--dry-run] [--root PATH]` | Applies approved fixes to the files |
| `review.py RUN --summary TEXT` | Drafts a GitHub review from approved fixes as `RUN/review.json` (doesn't post) |

`apply.py` and `review.py` read approvals from `decisions.json`. When the user pasted their
decisions into the chat instead, pass `--approve F1,F3,...`.

## 1. Gather the feedback

The feedback can be a review you wrote in this session, another agent's output, a file, or
notes pasted into the chat. If a review skill produced it, follow that skill's guidance on IDs,
categories, and priorities.

Cards need a location in a file. Feedback about a design choice, a plan, or anything else
without one doesn't belong on the page. Leave it out, and tell the user which items you left
out so they can decide on them in the chat.

## 2. Make a run folder

Use `/tmp/feedback-triage/<slug>/`, for example `/tmp/feedback-triage/pr-42/` or
`/tmp/feedback-triage/launch-email/`. Everything for this triage lives there.

## 3. Point at the source

Line numbers must come from the exact text the user will judge.

- **Pull request.** Check out the PR's head commit in its own worktree, so local edits on
  the user's branch can't shift lines:

  ```bash
  gh pr view N --json headRefOid,baseRefName
  git fetch origin <baseRefName> pull/N/head
  git worktree add --detach /tmp/feedback-triage/pr-N/checkout <headRefOid>
  ```

  Source: `{"kind": "pr", "root": "checkout", "url": "<PR URL>", "base": "origin/<baseRefName>"}`.
  GitHub links to each snippet are added automatically.
- **The user's own changes.** Use their checkout as `root`. Set `base` to what the work
  branched from (such as `origin/main`), or `HEAD` to cover only uncommitted changes. Kind
  `changes`.
- **Plain files.** `root` is the folder that contains them. Kind `files`, and no `base`.
- **Pasted text** (an email, a draft in the chat). Save it verbatim to
  `RUN/source/<name>.md` (or `.txt`, `.rst`, whatever fits), then treat it as plain files with
  `"root": "source"`.

A relative `root` is resolved from the run folder.

## 4. Check each item before making a card

Treat feedback as claims to check, including feedback you wrote yourself. Reviewers, and
agents especially, cite lines that don't exist, flag problems the text doesn't have, and
report the same problem more than once.

- **Find the text.** If the quoted text or the cited lines aren't there, or the problem isn't
  where the feedback says, drop the item.
- **Confirm the problem.** Check it against the source, the code, or the facts where you can.
  If you can't confirm it, keep the card and begin its `problem` with "Unverified:".
- **Merge duplicates** into one card, and name every item it covers in `problem`.
- **Keep items you disagree with** when the user might still want them, and put your
  disagreement in `counter`.

## 5. Write `findings.json`

Give each card an ID. Keep any IDs the feedback already uses, so the user can refer to items
the same way in the chat and on the page. If it has none, number the items `F1`, `F2`, and so
on, in the order they appear. Use the feedback's own categories when it has them. Otherwise,
pick a few plain ones, such as Bug, Accuracy, Clarity, and Style. Priority 1 breaks the work or
misleads its reader, 2 noticeably hurts it, and 3 is polish.

The cards are only as useful as their fields:

- **`counter`** is the strongest honest case against making the change: scope, audience,
  intent, or cost. It's what lets the user reject with confidence. Don't leave it empty or
  make it a straw man.
- **`replacement`** is the exact text of whole lines, with the file's indentation, that
  replaces the lines from `start` to `end`. Use `""` to delete them. Prefer one tight fix per
  problem. When a finding needs a structural move with no line-level edit, use `fixNote`
  instead.
- **Anchor with `match`** (a phrase quoted from the file) rather than line numbers wherever
  you can. The build finds the lines for you and fails if the quote is missing or matches
  more than once. Use `occurrence` (1-based) only when repetition is unavoidable.

```json
{
  "title": "PR #42 review",
  "source": {
    "kind": "pr",
    "root": "checkout",
    "label": "owner/repo#42",
    "url": "https://github.com/owner/repo/pull/42",
    "base": "origin/main"
  },
  "findings": [
    {
      "id": "F1",
      "category": "Accuracy",
      "priority": 1,
      "title": "Install guide names the wrong minimum Python",
      "problem": "The guide says Python 3.8 or later, but `pyproject.toml` requires 3.10.",
      "evidence": [{"text": "pyproject.toml, requires-python", "url": "https://..."}],
      "counter": "Older versions may still run the parts of the tool this guide covers.",
      "comment": "",
      "context": [
        {"file": "docs/install.md", "match": "Python 3.8 or later"},
        {"file": "pyproject.toml", "match": "requires-python", "around": 0,
         "label": "What the package requires"}
      ],
      "fixes": [
        {"file": "docs/install.md", "match": "Python 3.8 or later",

From atrnh/skills, MIT.

More from atrnh/skills