# Triage

> Use for bugs, small isolated fixes, or tiny changes that don't warrant the full architect→specify→plan→implement pipeline. Runs the direct implement→archive-ready lifecycle with implement and docs approvals, and escalates to architect if scope is larger than expected.

- Skill: `printpractical/triage` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add printpractical/triage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/printpractical/triage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: printpractical (https://skillmd.com/u/printpractical)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/printpractical/triage

---


# Triage

You are running the **triage** entry ramp. Use this for bugs, small fixes, and changes that touch a single component with no new seams and no interface changes. If you discover the change is larger, escalate to `architect`.

## Running the helper scripts

This skill bundles its helper scripts in its own `scripts/` directory (installed alongside this SKILL.md). Set `SKILL_DIR` to this skill's absolute path — shown as **Base directory for this skill** at the end of this file — then run the scripts from your **project root** (they operate on the project's `.changes/` and `CONTEXT.md` files):

```bash
SKILL_DIR="<absolute path to this skill's directory>"
```

All `node "$SKILL_DIR/scripts/..."` commands below depend on this. Never reference `packages/build/` — that path only exists in the toolkit's development repo, not in an installed skill.

## Your stance

Use the constructive challenge stance in `references/challenge-protocol.md`, but keep this workflow lightweight. Triage does **not** run formal `AV-*`, `SV-*`, or `RV-*` review, does not launch auditor/verifier roles, and does not use `review-log.mjs`. Ask the user only when a choice reaches the materiality boundary; if it does, the change normally belongs in `architect`. Auto-select conventional idiomatic local/private/reversible choices.

## Preconditions

Before checking status, creating a manifest, reading CONTEXT.md, or scanning code, obtain the goal and observable outcome, affected area, constraints and anti-goals, and whether requirements are formed, partially formed, or unformed. After selecting or creating the workspace, write `change-brief.md` from `references/templates/change-brief.md.tmpl`.

Check for an active change:
```
node "$SKILL_DIR/scripts/change-status.mjs"
```

If no active change, create one:
```
node "$SKILL_DIR/scripts/change-new.mjs" --title "<title>" --class small|bug [--language <lang>]
```

Load the active `manifest.yaml`. If `manifest.language` is set, use the `idioms` skill to load its matching pack for the challenge and refactor passes. If no matching pack is installed, state that and use the repository's language conventions and tooling rather than assuming pack guidance.

## Phase 1: Classify

Answer these questions before doing anything else:

1. **Is this isolated to a single component?** If it touches multiple components or crosses component boundaries → escalate to `architect`.
2. **Does it introduce a new seam or change an existing interface?** If yes → escalate to `architect`.
3. **Does it touch a firm seam?** If yes: is the change *within* the firm contract (implementation change, not contract change) or does it *alter* the contract? If it alters the contract → escalate to `architect` and apply the firm-change protocol.
4. **Is the fix clear and bounded?** If not → escalate to `architect`.

If escalating:
> "This change is larger than triage scope because: [reason]. I'll start an architect session instead."

Create a new manifest with `--class feature` and proceed with `architect`.

## Phase 2: Quick context

Read only what's necessary:
- The component's `CONTEXT.md` (if it exists)
- The relevant source files (not the whole codebase)
- Any firm seam the change touches (confirm we're not changing the contract)

Note any `Known-soft-spots` in the CONTEXT that are relevant. If the fix touches a known soft spot and a better solution exists, surface it — but get explicit approval before scope-expanding.

## Phase 3: Challenge and confirm

One or two focused questions — not a full interview, but enough to confirm the fix is right:
- What is the root cause? (Not just the symptom)
- Is this the right fix, or a workaround for a deeper issue?
- Are there other callers or consumers affected?
- If touching an idiom smell: is there a cleaner approach in the idioms pack?

## Phase 4: Quick plan

Write a short plan inline — not a full `plan.md` unless the change warrants it:

```
## Triage Plan: <title>

Root cause: <one sentence>
Fix: <what you're doing>
Files: <target files>

Tasks:
- [ ] <task 1>
- [ ] <task 2>
- [ ] Write test: <what it asserts> [seam: <id if applicable>, firmness: soft|firm]
- [ ] Run tests
```

For bugs: write a **failing test that reproduces the bug first** before fixing it. This confirms the root cause and prevents regression.

Save to `.changes/active/<id>/plan.md` if using the full change workspace.

## Phase 5: Execute + lightweight self-check

Implement the tasks. Then do one quick implementer self-check, not a formal discovery/remediation/verification cycle:
- Did the fix introduce any new debt?
- Is there a cleaner way to express this?
- Check the idioms pack for anything relevant — especially unsafe/panic-prone code (e.g. Rust `.unwrap()`/`.expect()` on I/O), swallowed errors, and oversized modules.

Run tests — must pass.

If the fix grows beyond a small isolated change, stop and route it to the full `architect` spine or the `refactor` skill instead.

## Phase 6: Docs reconciliation

Reconciliation and verification are required before docs approval. For every relevant `CONTEXT.md` target:
- Update the relevant CONTEXT.md section.
- Re-stamp provenance.
- Run verification and resolve any finding:
  ```
  node "$SKILL_DIR/scripts/context-verify.mjs" --path <context-file>
  ```

## Phase 7: Archive-ready and verified archive

After the lightweight self-check and docs reconciliation, approve implement then docs. This moves the direct triage lifecycle to `archive-ready`:
```
node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval implement --approve
node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval docs --approve
```

Create the verified archive only after the change is archive-ready:
```
node "$SKILL_DIR/scripts/change-archive.mjs" --id <id>
```

For cancellation, record a concrete `archive.reason` in `manifest.yaml` and archive the current workspace rather than deleting it.

## Escalation conditions (summary)

Escalate to `architect` when any of these are true:
- Touches more than one component
- Adds or removes a seam
- Changes an interface (even slightly)
- Touches a firm seam's contract
- Fix requires a refactor of meaningful scope
- Root cause analysis reveals a deeper architectural issue

Do not be heroic about keeping something in triage. A legitimate escalation is not failure — it is honest scoping.

## Reference files

- `references/challenge-protocol.md`
- `references/context-schema.md` — for reading CONTEXT.md
- `references/seam-and-test-taxonomy.md`
- `references/firm-change-protocol.md` — if a firm seam is involved
- `idioms` skill — if language is set