What if validation fails?

Fix the JSON according to the validation errors and re-run the validation command before starting the triage server.

How do I stop a stuck triage server?

If the server is stuck, kill the port it's using (e.g., fuser -k 8741/tcp) and restart with the same or a new port.

What does INTENTIONAL mean in a triage decision?

INTENTIONAL marks an accepted risk with rationale; future reviews may downgrade the finding to INFO if the context changes.

triage-findings

Scanned

npx machina-cli add skill lklimek/claudius/triage-findings --openclaw

Files (1)

SKILL.md

3.7 KB

Interactive Finding Triage

Start an interactive triage session for review findings. The user classifies each finding in a browser UI, and decisions are written back to the report JSON.

Argument: $ARGUMENTS — path to the report.json file produced by grumpy-review or check-pr-comments.

Workflow

Validate the report JSON against the schema:
```
python3 scripts/validate_report.py "$ARGUMENTS"
```
Requires python3-jsonschema (apt install python3-jsonschema). If validation fails, fix the JSON and re-validate before proceeding. Do NOT start the triage server with invalid data.
Start the triage server (default port 8741):
```
python3 scripts/triage_server.py "$ARGUMENTS" [--port PORT]
```
The server auto-opens a browser. If that fails, it prints the URL for the user.
Wait for the user to complete triage in the browser and submit decisions. The server writes the triage field back into the report JSON and exits.

Killing a stuck server

The server normally shuts itself down when the user submits with complete=true. If it gets stuck, kill it by port — never use pkill -f (risks killing servers from other sessions):

fuser -k 8741/tcp    # kills whatever is bound to port 8741

Replace 8741 with the actual port if --port was used.

Read the updated report JSON. Summarize the triage results:
- How many findings were triaged
- Breakdown by action (fix, accept_risk, defer, false_positive, duplicate)
- List all fix decisions with their finding IDs and titles
For findings marked fix: use the finding's location, description, and recommendation fields to apply the recommended fixes. Work through them one at a time, verifying each fix before proceeding to the next.
For findings marked defer: add a TODO comment at the finding's location referencing the finding ID and title:
```
// TODO(SEC-004): BannerHandle is Send+Sync but read-modify-write is not atomic
```
Use the file's native comment syntax (//, #, , etc.).
For findings marked accept_risk: add an INTENTIONAL comment at the finding's location documenting the accepted risk and rationale:
```
// INTENTIONAL(SEC-005): Relaxed ordering adequate for single-threaded UI model
```
Include the rationale from the triage decision if provided, otherwise summarize from the finding's description. Future reviews that encounter an INTENTIONAL comment will downgrade the finding to INFO severity.

Comment-Check Reports

For reports with metadata.report_type == "comment_check" (produced by check-pr-comments):

Triage actions apply to unresolved PR review comments instead of code review findings
accept_risk / false_positive: after triage, resolve the associated GitHub review thread using gh-resolve-review-thread.sh with the finding's thread_id field. Always ask user confirmation before resolving threads.
fix: apply the fix described in recommendation, then resolve the thread
defer: leave the thread unresolved; add a TODO comment as usual
The triage decision's resolve_thread field (boolean) indicates whether thread resolution is appropriate for each decision

Output

The report JSON file is updated in-place with a triage field containing all decisions. This can be consumed by other tools or re-rendered with generate_review_report.py.

Source

git clone https://github.com/lklimek/claudius/blob/main/skills/triage-findings/SKILL.mdView on GitHub

Overview

triage-findings starts a browser-based session to classify review findings and write decisions back to the report.json. It validates the input against a schema, runs a local triage server, and ensures decisions are captured for subsequent fixes or risk actions. This streamlines handling grumpy-review or check-pr-comments outputs in a reproducible way.

How This Skill Works

You point the tool at a report.json produced by grumpy-review or check-pr-comments. It validates the JSON, starts a triage_server.py process on a local port, and opens a browser UI where you classify each finding. Once complete, the server writes a triage field into the report.json with your decisions.

When to Use It

You need to triage findings from a review report using an interactive browser UI.
You must classify findings into fix, accept_risk, defer, false_positive, or duplicate and update the JSON accordingly.
You want to run a repeatable triage session on a local server and capture results back to the report.
You need to summarize triage results (counts by action and a list of fix decisions) after triage.
You are dealing with comment_check reports and may resolve GitHub review threads after triage or apply appropriate TODO/INTENTIONAL comments.

Quick Start

Step 1: Validate the report JSON -> python3 scripts/validate_report.py "$ARGUMENTS"
Step 2: Start the triage server -> python3 scripts/triage_server.py "$ARGUMENTS" [--port PORT]
Step 3: Complete triage in the browser; review the updated report.json triage field for summaries and fixes

Best Practices

Validate the report JSON before starting and fix any schema errors prior to launching the server.
Use the default port 8741 or specify a port with --port; if the server locks up, use fuser -k to free the port.
Review findings one at a time in the browser UI to ensure accurate categorization.
After triage, review the triage field in the report.json and extract the fix IDs and titles for follow-up.
For defer or accept_risk, insert the proper TODO or INTENTIONAL comments in the relevant locations using the project’s native syntax.

Example Use Cases

Triaging findings from a PR report produced by grumpy-review and marking fixes for each item.
Processing a check-pr-comments output to triage unresolved review comments and plan thread resolutions.
Marking multiple findings as fix with their location, description, and recommendation for direct code changes.
Deferring a finding by adding a TODO comment at the finding's location in the target file.
Marking an accepted risk with an INTENTIONAL comment and capturing the rationale in the triage decision.

Frequently Asked Questions

Add this skill to your agents