lastlight 0.1.15 → 0.2.1

package/skills/issue-triage/SKILL.md

@@ -1,54 +1,120 @@
 ---
 name: issue-triage
-description: Triage GitHub issues — label, deduplicate, request info, and manage stale issues
+description: Triage GitHub issues through the canonical state machine — classify, label, deduplicate, request missing info, write agent briefs, and manage stale issues. Use on demand or on a triage cron.
 version: 2.0.0
 tags: [github, issues, triage]
 ---
 
-# Issue Triage Skill
+# Issue Triage
 
-## When to Use
-When asked to triage issues, or on a scheduled basis to process new/stale issues.
+Move each issue through a small **state machine**. Every triaged issue carries
+exactly **one category role and one state role**:
 
-## Procedure
+- **Category:** `bug` (something is broken) · `enhancement` (new feature or improvement)
+- **State:** `needs-triage` (awaiting evaluation) · `needs-info` (waiting on the
+  reporter) · `ready-for-agent` (fully specified, an AFK agent can take it) ·
+  `ready-for-human` (needs human implementation) · `wontfix` (won't be actioned)
 
-### For new issues (no labels yet):
+These are canonical role names; the actual label strings for a repo may differ —
+`docs/agents/triage-labels.md` holds the mapping when present. Run **autonomously**:
+there is no maintainer to ask mid-run. Where you'd want direction, either make
+the call and apply the label, or post a comment and stop — the async comment *is*
+the conversation.
 
-1. **Read the issue** carefully — title, body, and any linked PRs or issues
-2. **Classify** the issue type:
-   - Bug report → label `bug` + priority label
-   - Feature request → label `enhancement`
-   - Question → label `question`
-   - Documentation → label `documentation`
-3. **Check for duplicates** by searching existing issues with similar keywords
-   - If duplicate found: comment linking to the original, add `duplicate` label, close
-4. **Assess completeness**:
-   - Bug without reproduction steps → add `needs-info`, comment asking for steps
-   - Feature without use case → add `needs-info`, comment asking for context
-5. **Set priority** based on severity and impact:
-   - `p0-critical`: Security, data loss, service down
-   - `p1-high`: Major feature broken, affects many users
-   - `p2-medium`: Minor feature broken, workaround exists
-   - `p3-low`: Cosmetic, edge case, nice-to-have
-6. **Add helpful labels**: `good first issue` for simple fixes, `help wanted` for community
+## 0. Ensure the labels exist
 
-### For stale issues:
+Before applying any label, create the canonical set idempotently with
+`github_create_label` (ignore 422 "already exists"):
 
-1. **Find issues** labeled `needs-info` with no activity for 14+ days
-2. **Check existing comments** before acting — use `list_issue_comments` to see if the bot has already posted a stale reminder. Look for comments from `last-light[bot]` that contain words like "reminder", "still need", or "closing". **Do NOT post a duplicate reminder.**
-3. **If no bot reminder exists yet**: post a gentle reminder asking if they still need help
-4. **If a bot reminder already exists** and 30+ days have passed with no response since: close with a kind message explaining why, and note they can reopen
-5. **If a bot reminder already exists** and it's been less than 30 days: skip — do nothing
+| Label | Color | Role |
+|-------|-------|------|
+| `bug` | `d73a4a` | category |
+| `enhancement` | `a2eeef` | category |
+| `needs-triage` | `ededed` | state |
+| `needs-info` | `fbca04` | state |
+| `ready-for-agent` | `0e8a16` | state |
+| `ready-for-human` | `1d76db` | state |
+| `wontfix` | `ffffff` | state |
+| `duplicate` | `cfd3d7` | dedupe |
+| `question` | `d876e3` | question |
 
-## Tool Usage
+If label creation is denied (the token lacks the permission), fall back to using
+only the labels that already exist on the repo and skip the rest. Done when the
+labels you need are present or you've confirmed you can't create them.
 
-**Always use MCP tools** (`mcp_github_*`) for all GitHub operations — listing issues, adding labels, posting comments, closing issues. Never use `gh` CLI, `curl`, or raw HTTP requests. The MCP server handles authentication.
+## 1. Triage a specific issue
+
+1. **Gather context.** Read the full issue — title, body, comments, existing
+   labels, author, dates. Search existing issues for **duplicates** by concept
+   (not just keyword). If a `.out-of-scope/` directory exists, read it and note
+   any prior rejection this resembles. Done when you know the issue's intent and
+   whether it's novel.
+2. **Classify the category** — `bug` or `enhancement`. But first, check whether
+   the issue is a **question** at all (see below) — questions are neither.
+3. **Decide the state and act** (exactly one applies):
+   - **Question** (asks for information, an explanation, or a comparison — wants
+     an answer, not a code change) → add `question` and **stop**. Do **not**
+     write an agent brief or mark it `ready-for-agent`/`ready-for-human` — a
+     pure question is not work. (The router normally sends these to the answer
+     path before triage runs; this is the safety net for ones that slip
+     through, e.g. reopened issues. If you can answer it briefly and factually
+     from the repo itself, do so in one short comment; otherwise just label it
+     and leave it for the answer path or a human.)
+   - **Duplicate** → comment linking the original, add `duplicate`, close.
+   - **Already implemented** → comment pointing to where it lives, add `wontfix`,
+     close. (Factual — safe to close autonomously.)
+   - **Under-specified** (bug without repro, feature without a use case) → add
+     `needs-info`, post the [needs-info template](#needs-info-template), stop.
+   - **Fully specified and delegatable** → add `ready-for-agent`, post an agent
+     brief ([references/AGENT-BRIEF.md](references/AGENT-BRIEF.md)).
+   - **Needs human implementation** (judgment calls, external access, design
+     decisions, manual testing) → add `ready-for-human` with a brief noting why
+     it can't be delegated.
+   - **Looks out of scope** (an enhancement you'd reject) → this is a maintainer
+     decision; do **not** auto-close. Add `needs-triage`, post a comment with
+     your reasoning (cite any matching `.out-of-scope/` file), and leave it for a
+     human.
+4. **Apply exactly one category + one state.** If the existing labels conflict
+   (two state roles), flag it in a comment and don't override — a maintainer may
+   have set them deliberately.
+
+## 2. New unlabelled issues (batch / cron)
+
+For each issue with no triage labels yet, run §1. Default new issues that need
+evaluation to `needs-triage`.
+
+## 3. Stale `needs-info`
+
+1. Find issues labelled `needs-info` with no activity for **14+ days**.
+2. **Check for a prior bot reminder** with `github_list_issue_comments` — look
+   for a `last-light[bot]` comment containing "reminder" / "still need" /
+   "closing". **Never post a duplicate reminder.**
+3. No reminder yet → post a gentle reminder asking if they still need help.
+4. Reminder exists and **30+ days** have passed with no reporter response since →
+   close kindly, noting they can reopen.
+5. Reminder exists, **< 30 days** since → do nothing.
+
+## needs-info template
+
+```markdown
+## Triage Notes
+
+**What we've established so far:**
+- point 1
+
+**What we still need from you (@reporter):**
+- specific, actionable question 1
+```
+
+Questions must be specific and actionable — not "please provide more info".
+
+## Tool usage
+
+GitHub operations via `github_*` MCP tools only — listing, labelling, commenting,
+closing, creating labels. Never `gh` CLI, `curl`, or raw HTTP.
 
 ## Pitfalls
-- Don't close issues too aggressively — when in doubt, leave open
-- Don't change priority on issues already triaged by maintainers
-- Don't duplicate labels (check existing labels first)
 
-## Verification
-- List the actions taken (labels added, comments posted, issues closed)
-- Confirm each action via the GitHub API response
+- Don't close aggressively — when genuinely in doubt, leave it open as `needs-triage`.
+- Don't change priority or state on issues a maintainer already triaged.
+- Check existing labels before adding — don't duplicate.

package/skills/issue-triage/references/AGENT-BRIEF.md

@@ -0,0 +1,61 @@
+# Writing agent briefs
+
+An agent brief is a comment posted when an issue moves to `ready-for-agent`
+(or `ready-for-human`). It is the **contract** an AFK agent will build from — the
+original body and discussion are context; the brief is what gets implemented.
+Post it with `github_add_issue_comment`.
+
+## Principles
+
+**Durable.** The issue may sit in `ready-for-agent` for weeks while the codebase
+moves. Describe interfaces, types, and behavioural contracts — name specific
+types, function signatures, or config shapes to look for. **Never** reference
+file paths or line numbers; they go stale. Don't assume today's structure survives.
+
+**Behavioural, not procedural.** Say *what* the system should do, not *how* to
+code it — the agent explores fresh and makes its own implementation calls.
+- Good: "`SkillConfig` should accept an optional `schedule: CronExpression`."
+- Bad: "Add a `schedule` field in src/types/skill.ts on line 42."
+
+**Complete acceptance criteria.** Every brief lists concrete, independently
+testable criteria so the agent knows when it's done.
+- Good: "`gh issue list --label needs-triage` returns issues that passed initial classification."
+- Bad: "Triage should work correctly."
+
+**Explicit scope boundaries.** State what is *out of scope* so the agent doesn't
+gold-plate or wander into adjacent features.
+
+## Template
+
+```markdown
+## Agent Brief
+
+**Category:** bug / enhancement
+**Summary:** one line — what needs to happen
+
+**Current behavior:**
+What happens now. For a bug, the broken behaviour. For an enhancement, the
+status quo it builds on.
+
+**Desired behavior:**
+What should happen after the work is done. Be specific about edge cases and
+error conditions.
+
+**Key interfaces:**
+- `TypeName` — what changes and why
+- `functionName()` — current vs intended return/behaviour
+- Config shape — any new options
+
+**Acceptance criteria:**
+- [ ] Specific, testable criterion 1
+- [ ] Specific, testable criterion 2
+
+**Out of scope:**
+- Thing that should NOT be changed here
+- Adjacent feature that looks related but is separate
+```
+
+## `ready-for-human` variant
+
+Same structure, plus a leading note on **why it can't be delegated** — judgment
+calls, external access, design decisions, or manual testing the agent can't do.

package/skills/pr-comment/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: pr-comment
+description: Answer a maintainer's question about an open PR with concrete, code-cited evidence. The PR-side counterpart to issue-comment — for questions tied to the diff, not a full review.
+version: 2.0.0
+tags: [github, pr, comments, qa]
+---
+
+# PR Comment
+
+A maintainer @mentioned the bot on a PR with a *question* (not a request to
+write code, and not "review this"). The question is the entire job — answer it
+with evidence, in one comment. Examples: "does this consider X?", "why did we
+change Y?", "is the new function thread-safe?", "regression risk for existing
+callers?".
+
+For general issue questions use `issue-comment`; for a full review use
+`pr-review`.
+
+## Procedure
+
+### 1. Read the PR and the question
+
+- `github_get_pull_request` → title, body, base, head.
+- The triggering question is in `context.commentBody`. Answer *that* question —
+  don't generalise to a review or answer a different one.
+
+### 2. Investigate with the diff in hand
+
+Get the diff and read the code needed to answer well — a real answer about
+thread-safety or regression risk needs the surrounding code, not just the hunk.
+
+- **Cap: 8 file reads** per invocation.
+- "Does it consider X?" → also check whether tests in the diff cover X.
+- "Regression risk?" → find callers of any function whose signature/behaviour
+  changed (`github_search_code`).
+- Don't clone the repo unless a single answer genuinely needs cross-file traces
+  no MCP tool can give — most don't. If it truly needs a full audit, say so and
+  recommend `@last-light` (which routes to `pr-review`) rather than blowing the cap.
+
+### 3. Reply with one comment
+
+`github_add_issue_comment` (PRs accept issue comments here). Keep it tight:
+
+- **Lead with the answer** — yes / no / it depends. Don't bury it.
+- **Cite `path:line`** — clickable in the GitHub UI.
+- 3–8 sentences or a short bulleted list. No headings.
+- If it's unanswerable from the PR alone, say so and name the specific
+  information you'd need.
+
+> Yes — `src/foo.ts:42` checks `X` before calling `bar()`, and
+> `tests/foo.test.ts:118` asserts the rejection path. The only place X isn't
+> validated is the legacy `barLegacy` (`src/foo.ts:67`), which this PR doesn't
+> touch — worth a separate issue if you want it covered.
+
+## Do not
+
+- Post a formal review (`github_create_pull_request_review`) — that's
+  `pr-review`'s job and would collide with its blocking check.
+- Modify code, push, or add labels. One comment, nothing else.
+- Answer a tangent you noticed — note it in at most one trailing sentence.
+
+## Tool usage
+
+GitHub operations via `github_*` MCP tools only — never `gh` CLI, `curl`, or raw HTTP.

package/skills/pr-review/SKILL.md

@@ -1,74 +1,90 @@
 ---
 name: pr-review
-description: Review a GitHub pull request with structured feedback following project guidelines
-version: 2.0.0
+description: Review a GitHub pull request and post one formal review — advance the existing discussion, verify by building, and give tiered feedback. Use when asked to review a PR or on a cron PR scan.
+version: 3.0.0
 tags: [github, review, code-quality]
 ---
 
-# PR Review Skill
+# PR Review
 
-## When to Use
-When asked to review a pull request, or when triggered by a webhook/cron to check for unreviewed PRs.
+Review an open PR and post **one formal review**. Build and test the change for
+real — static reasoning alone is not a review of correctness.
 
-## Procedure
+This skill is the PR-specific procedure. It uses two shared skills: the
+**building** skill for installing and running the test/lint/typecheck gate, and
+the **code-review** skill for the finding tiers and what-to-check rubric.
+
+## Workspace
 
-### 0. Check if already reviewed
+The harness pre-clones the PR's head ref into a `<repo>/` **subdirectory** of
+your cwd (the cwd holds `AGENTS.md`; the repo is one level deeper). `ls -la` —
+if you see `<repo>/.git/`, `cd <repo>` and use git directly. To refresh:
+`git fetch origin <branch> --depth 50 && git reset --hard FETCH_HEAD`. If the
+pre-clone is missing, `git clone https://github.com/{{owner}}/{{repo}}.git {{repo}}`.
 
-Before reviewing, **always check if the bot has already reviewed this PR**:
-1. Use `list_pull_request_files` to get the PR head SHA
-2. Use `get_pull_request` to check existing reviews
-3. Look for reviews from `last-light[bot]` — if one exists on the current head SHA, **skip this PR**. Do NOT post a duplicate review.
-4. If the PR has new commits since the last bot review, a re-review is appropriate.
+**Read code from this local checkout, never the API.** Use `git`/`read`/`grep`
+on disk for the diff and file contents. Do **not** call
+`github_get_pull_request_diff`, `github_list_pull_request_files`, or
+`github_get_file_contents` — the API patch is a large redundant payload that
+re-bloats context every turn. The `github_*` tools are for *API* operations only
+(metadata, comments, posting the review).
 
-### 1. Fetch PR metadata
+## Procedure
 
-Using MCP tools:
-- Get the PR title, description, author, labels, and linked issues
-- Get the list of changed files and the diff
-- Skip PRs authored by `last-light[bot]` (self-review)
+### 1. Confirm the target
 
-### 2. Analyze the changes
+If `prNumber` (or `issueNumber`) is set in the Context block, **that is your
+target** — go straight to `github_get_pull_request` with it. Do **not** call
+`github_list_pull_requests` to "find" or "confirm" it; you were handed it, and
+listing dumps a large payload for nothing. Only when no PR is given (a repo-wide
+`mode: scan`) do you list open PRs and pick the most recent unreviewed one.
 
-- Read each changed file in context (not just the diff)
-- Check against the review guidelines in your agent context
-- Note the PR size (files changed, lines added/removed)
+**Stop conditions** (check before reviewing):
+- PR authored by `last-light[bot]` → skip. Never self-review.
+- `merged === true` → stop. This skill reviews open PRs only.
+- A `last-light[bot]` review already exists on the **current head SHA** → stop;
+  don't post a duplicate. (A re-review is fine once new commits land.)
 
-**For complex PRs** (>300 lines changed OR >5 files changed):
-- Clone the repo locally and read changed files in FULL context
-- Trace data flow through modified functions
-- Check callers of modified functions for regression risk
-- Check if tests cover actual risk areas, not just happy paths
+### 2. Read the prior discussion
 
-### 3. Categorize findings
+A review advances the conversation, don't restart it. Fetch and absorb:
+`github_list_pull_request_reviews`, `github_list_issue_comments`,
+`github_list_pull_request_review_comments`. Done when you can say: which findings
+were already raised (don't repeat them), which threads the author resolved
+(treat as done unless the fix is wrong), which are still open (surface those —
+higher signal than a fresh nit), and whether a human already approved.
 
-- **Critical**: Security issues, data loss, breaking changes — block merge
-- **Important**: Missing tests, perf issues, type errors — should fix
-- **Suggestions**: Clarity, naming, DRY opportunities — nice to have
-- **Nits**: Style, formatting — optional
+### 3. Get the diff
 
-### 4. Write the review comment
+From inside `<repo>/`:
+```
+git fetch origin <baseRef> --depth 50      # base isn't in the head-only clone
+git diff --stat origin/<baseRef>...HEAD    # churn
+git diff origin/<baseRef>...HEAD           # the patch
+```
 
-- 1-2 sentence summary of what the PR does
-- Findings grouped by tier, with file:line references
-- Inline code suggestions where helpful
-- For complex PRs: impact analysis (affected code paths, regression risks)
-- Overall assessment: approve, request changes, or comment
-- Thank the contributor
+### 4. Verify by building
 
-### 5. Submit the review
+Follow the **building** skill: install dependencies (install-first), then run the
+project's build and tests, and cite the real output in your findings. Any PR that
+touches code must be built and tested. The one exception is a pure style/docs PR,
+where building to nitpick formatting is wasted effort — skip it and say so.
 
-Use `create_pull_request_review` MCP tool. Do NOT post as a regular comment.
+### 5. Assess and submit
 
-## Tool Usage
+Apply the **code-review** skill's rubric — read each changed file in context,
+check correctness/edge-cases/security/regression-risk/test-coverage, and
+categorise findings into the tiers. Then write the review:
 
-**Always use MCP tools** for all GitHub operations. Never use `gh` CLI, `curl`, or raw HTTP requests.
+- One or two sentences on what the PR does.
+- Findings grouped by tier, each with a `path:line` reference and an inline code
+  suggestion where it helps.
+- For a complex PR, an impact note (affected paths, regression risks).
+- An overall assessment, and thanks to the contributor.
 
-## Pitfalls
-- **Never review the same PR twice** at the same commit — always check first
-- Don't nitpick generated files (lock files, compiled assets)
-- Don't repeat what linters/CI already catch
-- Don't block PRs over style preferences alone
-- Skip PRs authored by the bot itself
+Submit with `github_create_pull_request_review` (a **formal** review, not a plain
+issue comment), event `APPROVE` / `REQUEST_CHANGES` / `COMMENT` to match.
 
 ## Verification
-- Confirm the review was posted by checking the PR reviews list
+
+Confirm the review posted by checking the PR's reviews list.

package/skills/qa-test/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: qa-test
+description: Run an automated QA flow against a CLI or a locally-served app and report step-level pass/fail with evidence. Use when asked to QA-test a feature, exercise a flow end-to-end, or smoke-test what a PR changed.
+version: 1.0.0
+tags: [github, qa, testing, evidence]
+---
+
+# QA Test
+
+Drive a target through a sequence of steps and report **step-level pass/fail**
+with evidence for each step. The deliverable is a QA report, not a single
+verdict — partial coverage with documented failures is the expected output.
+
+This skill uses the **building** skill for installing dependencies and running
+the repo's build/run commands in the sandbox.
+
+> **Scope (text-evidence path).** In the default text phase the sandbox agent
+> has bash, file read, and the github tools — no browser, no screenshots. QA a
+> **CLI** directly, or a **web service** by starting its dev-server in the
+> background and exercising it with `curl` (status codes, response bodies,
+> headers). Capture stdout/stderr, exit codes, and log excerpts as per-step
+> evidence. Driving a real browser UI and attaching screenshots is the separate
+> `browser-qa` skill, staged only in the gated browser phase running on the
+> docker QA image (Playwright + Chromium). If that skill isn't in your
+> catalogue, mark a step that genuinely needs rendered-UI interaction
+> **BLOCKED** with the reason rather than faking a result — the browser phase
+> will pick it up when available.
+
+## Parse the target
+
+The Context block gives you what to test and (usually) a PR/issue. The target
+may be:
+
+- A **CLI command** (`my-cli --flag`, a subcommand) → run it directly.
+- A **local web service** (an app the repo serves on a port) → start it, hit it
+  with `curl`.
+- A **PR reference + focus area** → read the diff and infer the flow that
+  exercises what changed.
+- A **free-text flow** ("create a project, then list it") → infer concrete steps.
+
+When a PR/issue is given, read its description + diff (from the local checkout —
+see the **building** skill) to decide what's worth testing.
+
+## Define the steps
+
+If the request specifies steps, use them. Otherwise design a reasonable flow:
+
+- **CLI**: invoke with valid input → assert output/exit code → invoke an edge
+  case (bad flag, missing arg) → assert it's handled → done.
+- **Web service**: start the server → wait until it's ready → hit the primary
+  endpoint(s) → assert status + body → hit an error case → assert handling →
+  stop the server.
+
+State the steps and their success criteria before running. If the flow or the
+success criteria are genuinely ambiguous and you can't infer them from the diff,
+say what's unclear in the report rather than inventing a pass.
+
+## Run each step
+
+Follow the **building** skill to install and build first. Then run each step in
+order, capturing evidence (command + stdout/stderr + exit code) at every step.
+
+- **Record each step's result as you go** — PASS, FAIL, or BLOCKED.
+- **On failure, continue to the next step** for maximum coverage — *unless* the
+  failure blocks everything downstream (e.g. the server never starts, or a login
+  step fails). If it's a hard blocker, record it, mark the rest BLOCKED, and stop.
+- Treat a wrong result as a real finding, not your mistake. Don't edit the code
+  under test to make a step pass.
+
+## Report
+
+Produce your report as your **final message** in this shape — the workflow posts
+it for you (don't `github_add_issue_comment` yourself; that would double-post).
+**Keep it concise**: a one-line environment summary, the results table (terse
+Evidence cells), the failures, and a short coverage note — not a step-by-step
+narration.
+
+```
+## QA Test: <target>
+
+**Environment:** <branch / commit, package manager, how the app was run>
+
+### Results
+| Step | Status | Evidence |
+|------|--------|----------|
+| <step description> | PASS / FAIL / BLOCKED | <command + key output / exit code> |
+
+### Issues found
+- <each FAIL with the expected vs observed behaviour and the evidence>
+
+### Coverage
+<what was tested, and what was not tested and why (e.g. a UI-only step that the
+text-evidence sandbox can't drive).>
+```
+
+Every defined step must have a row and a result. Never report a flow as
+"passed" with steps you didn't actually run — list them as untested instead.

package/skills/repo-health/SKILL.md

@@ -1,64 +1,67 @@
 ---
 name: repo-health
-description: Generate a health report for a GitHub repository — open issues, PR backlog, CI status
-version: 1.0.0
-metadata:
-  hermes:
-    tags: [github, monitoring, reporting]
-    category: maintenance
-    requires_toolsets: [terminal]
+description: Generate a health report for a GitHub repository — open-issue and PR backlog, unreviewed PRs, stale needs-info, failing CI, and the resulting action items. Use for a status report or on a weekly cron.
+version: 2.0.0
+tags: [github, monitoring, reporting]
 ---
 
-# Repository Health Check Skill
+# Repo Health
 
-## When to Use
-When asked for a repo status report, or on a weekly cron schedule.
+Produce a point-in-time health snapshot of a repo and the action items it
+implies. One report per run.
 
 ## Procedure
 
-1. **Gather metrics** for the target repository:
-   - Open issue count, broken down by label/priority
-   - Open PR count, and how long each has been open
-   - PRs awaiting review (no reviews yet)
-   - Issues labeled `needs-info` with no response
-   - Recently closed issues and merged PRs (last 7 days)
+### 1. Gather metrics
 
-2. **Identify action items**:
-   - PRs open > 7 days with no review
-   - Issues labeled `p0-critical` or `p1-high` still open
-   - Stale `needs-info` issues (14+ days)
-   - PRs with failing CI
+Pull these via `github_*` MCP tools. Done when each number below is filled.
 
-3. **Generate a summary report** in markdown:
-   ```
-   ## Repo Health: owner/repo — YYYY-MM-DD
+- **Open issues** — total, and a breakdown by the repo's own priority/severity
+  labels *if it uses any* (don't assume a fixed scheme).
+- **Open PRs** — total, and how long each has been open. Exclude drafts from any
+  "awaiting review" count.
+- **Unreviewed PRs** — open, non-draft, no reviews yet.
+- **Stale `needs-info`** — issues labelled `needs-info` with no activity for 14+ days.
+- **Recent throughput** — issues closed and PRs merged in the last 7 days.
 
-   ### Overview
-   - Open issues: X (Y critical, Z high)
-   - Open PRs: X (Y awaiting review)
-   - Merged this week: X PRs
-   - Closed this week: X issues
+Batch requests and don't fetch full history — rate limits bite on large repos.
 
-   ### Action Items
-   - [ ] PR #123 — open 12 days, no review
-   - [ ] Issue #456 — p0-critical, open 3 days
-   - [ ] Issue #789 — needs-info, stale 21 days
+### 2. Derive action items
 
-   ### Trends
-   - Issue velocity: +X opened, -Y closed (net: ±Z)
-   ```
+Each is a checkbox line with the number and the reason:
 
-4. **Deliver the report**:
-   - In interactive mode: display directly
-   - In gateway mode: send to the configured channel
+- PRs open > 7 days with no review.
+- High-priority issues still open (by whatever priority labels the repo uses).
+- `ready-for-agent` issues sitting unactioned (agent backlog).
+- Stale `needs-info` (14+ days).
+- PRs with failing CI.
 
-## Tool Usage
+### 3. Render the report
 
-**Always use MCP tools** (`mcp_github_*`) for all GitHub operations — listing issues, PRs, commits, labels. Never use `gh` CLI, `curl`, or raw HTTP requests. The MCP server handles authentication.
+```markdown
+## Repo Health: {owner}/{repo} — {YYYY-MM-DD}
 
-## Pitfalls
-- Don't include draft PRs in the "awaiting review" count
-- API rate limits: batch requests, don't fetch full history unnecessarily
+### Overview
+- Open issues: {X} ({breakdown by the repo's priority labels, if any})
+- Open PRs: {X} ({Y} awaiting review)
+- Merged this week: {X} PRs · Closed this week: {X} issues
+
+### Action items
+- [ ] PR #123 — open 12 days, no review
+- [ ] Issue #456 — high priority, open 3 days
+- [ ] Issue #789 — needs-info, stale 21 days
+
+### Trends
+- Issue velocity: +{X} opened, −{Y} closed (net {±Z})
+```
+
+Omit a section that has nothing in it rather than printing "none".
+
+### 4. Deliver
+
+Output the report as the final response. The harness routes it (direct display
+interactively, or to the configured channel on a cron run).
 
 ## Verification
-- Spot-check 2-3 numbers against the GitHub web UI
+
+Spot-check 2–3 of the reported numbers against the GitHub UI before delivering.