Skip to content

simiancraft/simiancraft-skills / skills/appraise-github-issues

appraise-github-issues

Verified

Appraise a GitHub issue backlog unattended: for each issue, decide whether it is still real and how big it is, then apply the answer to the tracker as a size label, a needs-decision or needs-human label with the question stated, or a close carrying a re-checkable receipt. A close is confirmed by a second engine before it is made. Runs once, on one issue, over the whole backlog, or as a periodic heartbeat, and is the sizing stage of burn-down-github-issues. Use when the task is "size the backlog", "appraise every issue in this repo", "close what is already done", "triage recent issues without fixing them", or "keep the backlog sized". Requires a per-repository config (its own, or the burndown's) and the codex and claude CLIs for the default seats. Skip for fixing anything; this skill never writes to the repository.

FileKindSize
SKILL.mdskill md7.1 KB
appraise.tsscript12.7 KB
lib/appraise.test.tsscript2.8 KB
lib/appraise.tsscript30.9 KB
lib/callbacks.tsscript4.1 KB
prompts/appraise.mdmarkdown6.2 KB
prompts/confirm-close.mdmarkdown3.3 KB
references/adopting.mdmarkdown4.0 KB
references/callbacks.mdmarkdown3.4 KB

prompts/appraise.md

View on GitHub
You are appraising issue **#{{ISSUE}}** of the {{PROJECT}} repository: "{{TITLE}}".

You are running headless. Nobody will answer a question, so a question is a verdict, not a pause.

**You do not fix anything.** You answer two questions about this issue and stop: is it still real,
and how big is it. A worker picks up what you pass through, so your judgement decides what the
expensive population spends its time on. Being wrong in the generous direction wastes a worker's
whole run; being wrong in the strict direction buries real work.

This is a read-only job. Your working directory is an empty scratch directory, not a checkout, and
it carries no repository context: address GitHub explicitly with `gh -R {{REPO}}`. The repository's
main checkout is at `{{MAIN_CHECKOUT}}`; read code from it freely, but treat it as someone else's
desk: write nothing there, switch no branches, and run nothing in it that creates files. Do not
create a branch, do not edit a file anywhere, do not open a pull request, and do not run the test
suite or install dependencies.

The checkout's working state is not evidence: it may be stale, dirty, or on another branch
entirely. Judge "already in `{{BASE_BRANCH}}`" against the fetched base ref, which the driver
refreshes before you start: `git -C {{MAIN_CHECKOUT}} show {{REMOTE}}/{{BASE_BRANCH}}:<path>`
reads a file as the base holds it, and `git -C {{MAIN_CHECKOUT}} log {{REMOTE}}/{{BASE_BRANCH}}`
its history.

When the driver applies a window it is {{AGE_DAYS}} days (`any` means no window), so recency is
already decided; your judgement is whether the issue's claim still holds, not whether it is recent.

## Step 1: is it still real

`gh -R {{REPO}} issue view {{ISSUE}} --comments`, then read the code it points at. **Read the whole comment
thread, not just the body.** The body is usually the original analysis; the comments are where
rulings land, so an issue that looks decision-blocked from its body is often already decided
further down.

Reach a verdict from what you find in the code today, not from the issue's own framing. An issue
in the window can be far older than it looks, and its claim may no longer hold.

| Verdict | When |
|---|---|
| `valid` | The problem is real, present in the code now, and someone could act on it |
| `already-fixed` | The change it asks for is already in `{{BASE_BRANCH}}` |
| `obsolete` | Its premise no longer holds: the code, route, or component it describes is gone or reshaped so the defect cannot occur |
| `needs-decision` | Blocked on a product or domain ruling rather than on effort. Any issue asking a person to decide, settle, rule on, or confirm something, unless the thread already contains that ruling |
| `needs-human` | Needs access or authority an agent does not have: production data edits, account provisioning, third-party configuration, or asset creation |

Three rules decide most of the hard cases:

- **A decision beats a small diff.** If the correct value depends on knowledge of the product, the
  business, its operations, or its customers, and nobody has ruled on it in the thread, it is
  `needs-decision` however small the change would be.
- **Never edit production data.** An issue asking for a record to be corrected is
  `needs-human`.
- **A well-argued issue can still prescribe the wrong remedy, and the convention wins.** Issues
  often prescribe a fix, not just a defect, and that prescription is the author's opinion rather
  than a ruling. Read it against {{CONVENTION_DOCS}}, and what the surrounding code plainly does. Where they disagree, the written convention wins and the issue is still `valid`: size the
  work the convention implies, not the work the issue proposed, and say in `reason` which remedy you
  sized and why it differs. This does not need a human. A documented convention is already a ruling;
  deferring to it is following the decision, not making one.

  Escalate to `needs-decision` only when the convention-respecting remedy is itself blocked: it
  exceeds what a worker may attempt, or it turns on a value nobody has ruled on. Size it, say so,
  and let the point ceiling do the stopping rather than stopping yourself.

For `already-fixed` and `obsolete`, write a `closeComment` a reader can re-check without trusting
you: the commit SHA plus the output of `git merge-base --is-ancestor <sha> {{BASE_BRANCH}}` for
already-fixed, or the file and line as it stands today for obsolete. State what the issue asked for
and why it no longer applies.

## Step 2: how big is it

Size it against the scale on {{SIZING_SCALE}}; where that scale differs from the table below, the
repository's scale wins. Points measure complexity, effort, uncertainty, and dependencies
together, not hours alone:

| Points | Meaning |
|---|---|
| 1 | 15 to 60 minutes; a tiny change, a config tweak, one line |
| 2 | 1 to 2 hours; a small isolated task with little risk |
| 3 | 2 to 4 hours; a small feature or a straightforward fix |
| 5 | half a day to a day, with some unknowns |
| 8 | 1 to 2 days; moderate feature or integration work |
| 13 | 2 to 3 days spanning several components |
| 21 | 3 to 5 days, near the point where it should be split |

Size the work the issue actually requires, not the work you would like it to be. An issue whose fix
is one line but which needs a rendered before-and-after across four surfaces is not a 1. Count the
proof the change will owe as part of its size.

If the issue is already carrying a `size: N` label, still form your own judgement and say so; a
disagreement is worth recording.

## Step 3: write the verdict

Write `loop-appraisal.json` in the directory you were started in. This file is the only thing the
driver reads, so write it even when you failed.

```json
{
  "issue": {{ISSUE}},
  "verdict": "valid | already-fixed | obsolete | needs-decision | needs-human | failed",
  "points": 2,
  "reason": "one or two sentences; for needs-decision, the exact question a human must answer",
  "closeComment": "only for already-fixed and obsolete: the full comment to post, receipt included",
  "priorSize": "the size label it already carried, or null",
  "disagrees": false
}
```

Set `disagrees` to true when your points differ from a `size: N` label already on the issue, and say
why in `reason`. Be accurate rather than generous: a verdict the driver acts on is worth more than
one that flatters the backlog.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall