pi-dev-team 0.2.0

package/skills/test-improve/references/phase-9-report.md

@@ -0,0 +1,62 @@
+Produce a stable executive-summary report from the shipped template. Every
+section is present in every run; empty sections **do not disappear** — they
+render `_Not applicable — <reason>._` so the shape of the report never changes
+between runs.
+
+**Template source.** Copy
+`plugins/dev-team/skills/test-improve/templates/executive-summary.md` to the
+output path.
+
+**Output path.** `.dev-team-reports/test-improve/<slug>/report-<date>.md` —
+the file is always relative to the invocation directory, whether the run used
+a tracker sink or local-files mode. Its git-tracked `data/` sibling is
+`.dev-team-reports/test-improve/<slug>/data/`.
+
+**Interpolation.** Every placeholder is **interpolated** from two sources:
+the git-tracked `.dev-team-reports/test-improve/<slug>/data/` directory
+(`test-counts-before.json`, `test-counts-after.json` if Phase 8 ran,
+`baseline-coverage.json`, `baseline-mutation.json` in `baseline+kill-loop`
+mode, and `coverage-history.json` — each already current there, written
+directly at the point of capture by Phase 2 and Phase 5 respectively), and the
+process/audit state still under `.claude/memory/test-improve/<slug>/`
+(`phase-0.md`, `phase-1.md`, `phase-4.md`, `phase-5-review.json`,
+`phase-7-review.json` if Phase 7 ran, `waivers.json`, `phase-8.md`), plus
+`.dev-team-reports/test-improve/<slug>/refactor-backlog.md` if Phase 6 chose
+`[b]` or Phase 8 wrote a no-refactor-mode entry to it. `mutation-history.json`
+is outside this interpolation set — and always has been; it is consumed by
+`/coverage-delta` and `/quality-targets-converge`, not by the
+executive-summary report, so its absence from this list is not the bug this
+plan fixes. `coverage-gap-ranking.json` (issue #1786) is outside it for the
+same reason: it is a targeting input read by Phases 1, 4, and 5, not a number
+the report interpolates. No placeholder is left literal.
+
+**Empty-section rule.** Sections with no data render `_Not applicable —
+<reason>._` (e.g. § 6 when Phase 7 was declined reads "*Phase 7 not run —
+operator chose to backlog REFACTOR_REQUIRED items at Phase 6.*"). Sections
+are never omitted or hidden — this keeps the report shape stable across runs.
+
+**Mutation row shape (per Phase-0 mutation mode).**
+
+- `off`: `_Not applicable — mutation disabled at Phase 0._`
+- `kill-loop`, non-Go: final surviving-mutant count from the Phase-5 kill loop;
+  the baseline and Δ cells read `_Not applicable — no baseline run (kill-loop
+  mode)._` since no Phase-2 baseline was taken.
+- `baseline+kill-loop`, non-Go: honest baseline-to-achieved score (hard kills /
+  effective total; timeouts reported separately) with the Δ column populated.
+- Go stack (`kill-loop` or `baseline+kill-loop`): honest numbers with the
+  "advisory only — go-mutesting is alpha" footnote.
+
+**Parent-issue-or-FEATURE.md link update.** When the run used a **parent
+tracker** (Phase 0 selected `--parent <url>`), the parent issue is updated
+with a link to `.dev-team-reports/test-improve/<slug>/report-<date>.md`. When
+the run was **local-files-only**, `.claude/plans/test-improve/FEATURE.md` is
+updated with the same link.
+
+**Regeneratable-from-tracked-data contract.** The report is a **pure
+function** of the git-tracked `.dev-team-reports/test-improve/<slug>/data/`
+directory (the numbers, already current by construction — each file was
+written directly there at the point of capture) plus the process/audit
+narrative still under `.claude/memory/test-improve/<slug>/`. Deleting the
+report file and re-invoking Phase 9 reproduces the report byte-for-byte —
+there is no copy step to re-run, and always exactly one place to read the
+numbers from; Phase 9 always reads `data/` directly, unconditionally.

package/skills/test-improve/references/review-loop.md

@@ -0,0 +1,92 @@
+Shared end-of-phase review loop: dispatch the `/code-review` panel once
+against the phase's diff, score the in-scope tests, apply fixes, confirm
+them, and iterate to a capped round count before escalating to the operator.
+Phase 5 and Phase 7 both invoke this loop verbatim against their own diff and
+write their own phase-numbered evidence file using the fixed schema below.
+
+1. **Dispatch the review panel — one panel per round (#1959).** Run
+   `/code-review --since <base-sha> --internal` against the diff between the
+   phase's base commit and HEAD. `--internal` (not `--json`) mirrors
+   `/build`'s Step 6 backstop-review flag choice: it suppresses the
+   `.dev-team-reports/code-review.md` write (this is a diff-scoped,
+   phase-internal review, not a human-invoked top-level run —
+   `knowledge/report-output-location.md`) while keeping the prose/
+   `corrections/` output sub-step 3 depends on — `--json` would skip that
+   output entirely.
+
+   **This loop no longer dispatches `/test-design` alongside the panel.**
+   `/test-design`'s two review agents — `test-review` and
+   `test-smell-review` — are both already in `/code-review`'s own roster for
+   this loop's changesets: `test-review` declares `Scope: always`, and
+   `test-smell-review` declares `Scope: test-files` (#1978), which
+   `scripts/select_lenses.py` resolves against
+   `knowledge/test-file-indicators.md`. A phase diff that adds or edits
+   tests — which is what this loop reviews, and what `refactor-mode:
+   no-refactor` guarantees — matches that scope by construction. Dispatching both skills against one
+   diff paid for the same two agents, over the same files, twice per round.
+   The panel still runs them; only the duplicate dispatch (and
+   `/test-design`'s own orchestration/aggregation layer) is gone.
+
+   **Confirm the two test lenses actually ran — do not assume the roster
+   kept them.** `/code-review`'s change-size gate (#1339) drops every
+   `Scope: always` agent outside its `keepAgents` floor on a small diff, and
+   `test-review`/`test-smell-review` are not in that floor. Read the panel's
+   reported roster (it names every gate-driven drop). If either lens was
+   dropped by a gate, dispatch it directly —
+   `/review-agent test-review --internal` and/or
+   `/review-agent test-smell-review --internal` — before proceeding. A
+   test-improvement phase whose review skipped both test lenses has reviewed
+   the wrong thing; this is the one lens pair this loop guarantees.
+
+   `/test-design`'s forward-design worker (`test-design-advisor`) is not lost
+   here either: it auto-fires only for untested production code or a
+   single-production-file target, and a Phase-5/7 diff under this loop is
+   test-and-seam-scoped, so it would not have fired. Reach for `/test-design`
+   directly when you want forward design for a specific module — it is
+   unchanged as a standalone skill and still runs inside `/test-health`.
+2. **Score the in-scope tests.** Invoke `Skill(farley-score ...)` scoped to
+   the phase diff's test files (indicators in
+   `knowledge/test-file-indicators.md`). This is the one input the evidence
+   schema needs that the panel does not produce; it is a direct worker call,
+   not an orchestrator dispatch.
+3. **Apply fixes, then confirm them narrowly (#1960).** Run
+   `/apply-fixes corrections/`. To confirm the fixes landed, **do not re-run
+   the full panel** — a whole-roster re-dispatch re-pays discovery cost to
+   answer a confirmation question. Confirm the way `/code-review` step 6a
+   and `/build`'s checkpoints already do:
+
+   - **Deterministic-first triage (#1610).** When a fix is mechanical and the
+     claim is deterministically checkable, close it with the project's own
+     stack tooling — its linter/type-checker (`ruff`/`mypy`, ESLint/`tsc`,
+     `pmd`, `dotnet format`/`dotnet build`, …), its test suite, or `grep` —
+     never an agent.
+   - **Verification-mode re-dispatch for the rest.** Re-dispatch **only the
+     agents whose findings were fixed**, with the narrowed payload and the
+     mandatory `insufficient-context` escape, resolving each agent's tier via
+     `python3 "$CLAUDE_PLUGIN_ROOT/scripts/verify_tier.py" --agent <name>`.
+     The payload contract, the escape's escalation path (an
+     `insufficient-context` reply earns a **full-context** re-dispatch of
+     that same agent at its discovery tier — never a shrug), and the
+     declared-never-inferred tier-down rule are stated once in
+     [`../../../knowledge/verification-mode.md`](../../../knowledge/verification-mode.md)
+     and are not restated here.
+
+   Discovery of *new* problems remains the initial panel's job (sub-step 1),
+   which is unchanged — this sub-step only cheapens confirming what was just
+   fixed.
+4. **Iterate at most 2 rounds.** After **2 iterations** without clean
+   `/code-review`, prompt the operator with **`[r]evise / [w]aive / [q]uit`**
+   (shape `[r/w/q]`).
+   - `[r]` triggers one more revise pass (may exceed the cap by operator
+     consent).
+   - `[w]` writes the outstanding finding set to
+     `.claude/memory/test-improve/<slug>/waivers.json`, **tagged** with the
+     finding list, and closes the phase.
+   - `[q]` quits the phase with the loop unresolved.
+5. **Evidence.** Write the calling phase's own review-evidence file with the
+   fixed schema — fields: `base_sha`, `head_sha`, `farley_score`, `smells`,
+   `code_review`, `iterations`, `escalated`. `farley_score` comes from
+   sub-step 2. `smells` comes from the panel's own `test-smell-review`
+   findings (sub-step 1) — the same agent's findings the removed
+   `/test-design` dispatch used to aggregate, read from the panel result
+   instead of from a second dispatch of it.

package/skills/test-improve/templates/executive-summary.md

@@ -0,0 +1,123 @@
+# /test-improve executive summary — {{repo_slug}} ({{run_date}})
+
+> Generated by `/test-improve` Phase 9 from the git-tracked `.dev-team-reports/test-improve/{{slug}}/data/` directory (see §3) plus the process/audit state under `.claude/memory/test-improve/{{slug}}/`. Regeneratable: delete this file and re-run Phase 9 against those persisted artifacts to reproduce it byte-for-byte.
+
+## 1. Bottom line
+
+{{bottom_line_narrative}}
+
+| Metric | Baseline | Achieved | Δ |
+| --- | --- | --- | --- |
+| Line coverage | {{baseline_line_cov}} | {{achieved_line_cov}} | {{delta_line_cov}} |
+| Branch coverage | {{baseline_branch_cov}} | {{achieved_branch_cov}} | {{delta_branch_cov}} |
+| Mutation score (hard kills) | {{baseline_mutation_hard}} | {{achieved_mutation_hard}} | {{delta_mutation_hard}} |
+| Mutation timeouts (reported separately) | {{baseline_mutation_timeouts}} | {{achieved_mutation_timeouts}} | {{delta_mutation_timeouts}} |
+| Determinism | {{baseline_determinism}} | {{achieved_determinism}} | {{delta_determinism}} |
+| Wall-clock (full suite) | {{baseline_wallclock}} | {{achieved_wallclock}} | {{delta_wallclock}} |
+
+_When mutation was disabled at Phase 0 (mode `off`), the mutation rows read **"Not applicable — mutation disabled at Phase 0."**_
+
+_When mutation mode was `kill-loop` (mutant-kill loop with no Phase-2 baseline), the Baseline and Δ cells read **"Not applicable — no baseline run (kill-loop mode)."** and Achieved carries the final surviving-mutant count. Only `baseline+kill-loop` populates the baseline and Δ cells._
+
+_When the stack is Go, the mutation row carries the footnote: **"Advisory only — go-mutesting is alpha; survivor count is not a gate for this run."**_
+
+### Tests by type
+
+| Type | Baseline | Achieved | Δ |
+| --- | --- | --- | --- |
+| Static analysis | {{baseline_static_analysis}} | {{achieved_static_analysis}} | {{delta_static_analysis}} |
+| Unit | {{baseline_unit}} | {{achieved_unit}} | {{delta_unit}} |
+| Component | {{baseline_component}} | {{achieved_component}} | {{delta_component}} |
+| Contract | {{baseline_contract}} | {{achieved_contract}} | {{delta_contract}} |
+| Integration | {{baseline_integration}} | {{achieved_integration}} | {{delta_integration}} |
+| End-to-end | {{baseline_end_to_end}} | {{achieved_end_to_end}} | {{delta_end_to_end}} |
+
+_Counts are test suites/files, not individual test cases. A type with zero
+suites still renders its row (`0 / 0 / 0`) — never omitted._
+
+_When `test-counts-after.json` does not exist (the operator quit before
+Phase 8 ran), every row's Achieved and Δ cells read **"Not applicable —
+Phase 8 not run."**; Baseline still renders from `test-counts-before.json`._
+
+## 2. What was done this run
+
+{{phase_summary}}
+
+- Phase 0 — approach contract resolved
+- Phase 1 — analysis via `/test-health`
+- Phase 2 — coverage {{mutation_baseline_phrase}} baseline captured
+- Phase 3 — {{gherkin_phrase}}
+- Phase 4 — {{triage_summary}}
+- Phase 5 — improve without refactoring
+- Phase 6 — refactor decision: `{{phase_6_choice}}`
+- Phase 7 — refactor-for-testability {{phase_7_phrase}}
+- Phase 8 — quality targets: {{targets_summary}}
+
+## 3. What was measured
+
+{{measurement_narrative}}
+
+Baseline artifacts (git-tracked under `.dev-team-reports/test-improve/{{slug}}/data/` — copied there unconditionally by Phase 9 from their canonical `.claude/memory/test-improve/{{slug}}/` working copy):
+
+- `baseline-coverage.json`
+- `baseline-mutation.json` — _Not applicable in `off` and `kill-loop` modes (no baseline run); advisory-only on Go `baseline+kill-loop`._
+
+Per-Story deltas:
+
+- `coverage-history.json`
+
+## 4. Findings from `/test-health`
+
+{{findings_summary}}
+
+Full analysis: `.claude/memory/test-improve/{{slug}}/phase-1.md`.
+
+## 5. Work completed (Phase 5 — no refactoring)
+
+{{phase_5_completed}}
+
+Review evidence: `.claude/memory/test-improve/{{slug}}/phase-5-review.json`.
+
+## 6. Work completed (Phase 7 — refactor-for-testability)
+
+{{phase_7_completed}}
+
+_When Phase 7 was declined: **"Phase 7 not run — operator chose to backlog REFACTOR_REQUIRED items at Phase 6."**_
+
+Review evidence: `.claude/memory/test-improve/{{slug}}/phase-7-review.json` — _Not applicable when Phase 7 did not run._
+
+## 7. Deferred work — areas requiring refactoring to add tests
+
+{{deferred_summary}}
+
+| Seam needed | Behavior gained | Estimated risk |
+| --- | --- | --- |
+| {{refactor_backlog_rows}} | | |
+
+_When `refactor-backlog.md` does not exist (no items were backlogged this run), this section reads **"Not applicable — no REFACTOR_REQUIRED items were backlogged this run."** instead of a table._
+
+Backlog file: `.dev-team-reports/test-improve/{{slug}}/refactor-backlog.md` — _Not applicable when no items were backlogged._
+
+## 8. Waivers
+
+{{waivers_summary}}
+
+Waivers file: `.claude/memory/test-improve/{{slug}}/waivers.json` — _Not applicable when no waivers were captured._
+
+## 9. Next actions
+
+{{next_actions}}
+
+## 10. Provenance
+
+- Repository: `{{repo_path}}`
+- Slug: `{{slug}}`
+- Branch / base SHA: `{{branch}}` / `{{base_sha}}`
+- Head SHA: `{{head_sha}}`
+- Run started: `{{run_started}}`
+- Run completed: `{{run_completed}}`
+- Phase-0 settings: `{{phase_0_recap}}`
+- Sink: `{{sink_description}}`
+- `/test-improve` version: `{{plugin_version}}`
+
+_This report is regeneratable from the git-tracked `.dev-team-reports/test-improve/{{slug}}/data/` directory (with baseline artifacts under it; see §3) plus the process/audit state under `.claude/memory/test-improve/{{slug}}/`. Delete and re-run Phase 9 to reproduce it._

package/skills/threat-modeling/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: threat-modeling
+description: Structured STRIDE security analysis for identifying threats, attack surfaces, and mitigations. Use before implementing any new API, service, authentication change, or data flow crossing trust boundaries — security analysis belongs in the design phase, not after.
+role: worker
+user-invocable: true
+---
+
+# Threat Modeling
+
+Role: worker. This command performs STRIDE analysis directly and documents
+threats/mitigations — it does not implement the mitigations it identifies.
+
+## Overview
+
+Structured security analysis for identifying threats, attack surfaces, and mitigations during design or review phases. Ensures security considerations are addressed before implementation, not after.
+
+## Constraints
+- Focus on trust boundaries, not implementation details
+- Every mitigation must map to a verifiable test or verification method
+- Document accepted risks explicitly with rationale; do not silently ignore threats
+- Revisit the threat model when architecture, authentication, or data flows change
+
+## Core Concepts
+
+### STRIDE Classification
+
+| Category | Definition | Example Threats |
+| --- | --- | --- |
+| **S**poofing | Pretending to be something or someone else | Forged authentication tokens, impersonated services |
+| **T**ampering | Modifying data or code without authorization | Altered request payloads, modified configuration files |
+| **R**epudiation | Denying an action was performed | Unlogged administrative actions, unsigned transactions |
+| **I**nformation Disclosure | Exposing data to unauthorized parties | Leaked credentials in logs, verbose error messages |
+| **D**enial of Service | Making a system unavailable | Resource exhaustion, unbounded queries |
+| **E**levation of Privilege | Gaining access beyond authorization | Broken access control, privilege escalation via injection |
+
+### Trust Boundaries
+
+Points where data crosses privilege levels. Every trust boundary is a potential attack surface. Common boundaries:
+
+- Client to server
+- Service to service (internal)
+- Application to database
+- System to external dependency
+- User role transitions
+
+### Attack Surface
+
+Entry points exposed to untrusted input: API endpoints, file uploads, message queues, configuration inputs, user-supplied queries. Smaller attack surface means fewer threats to mitigate.
+
+## Patterns
+
+### Threat Identification Procedure
+
+1. **Enumerate assets** — identify what needs protection (data, services, credentials, infrastructure)
+2. **Draw trust boundaries** — map where data crosses privilege levels
+3. **Identify entry points** — list all inputs exposed to untrusted sources
+4. **Classify threats per STRIDE** — for each entry point, apply each STRIDE category and document applicable threats
+5. **Rate severity** — assess impact (critical/high/medium/low) and likelihood for each threat
+
+### Mitigation Mapping
+
+| Threat Category | Standard Mitigations | Verification Method |
+| --- | --- | --- |
+| Spoofing | Authentication, mutual TLS, token validation | Auth integration tests, certificate verification |
+| Tampering | Input validation, integrity checks, signed payloads | Tampering test cases, checksum validation |
+| Repudiation | Audit logging, event sourcing, digital signatures | Log completeness review, signature verification |
+| Information Disclosure | Encryption at rest/in transit, access controls, log scrubbing | Security scan, log audit, access control tests |
+| Denial of Service | Rate limiting, resource quotas, circuit breakers | Load tests, resource monitoring |
+| Elevation of Privilege | Least privilege, role-based access, input sanitization | Authorization test matrix, penetration tests |
+
+### Threat Model Review Triggers
+
+Revisit the threat model when any of the following occur:
+
+- New external dependency added
+- New API endpoint or entry point exposed
+- Authentication or authorization changes
+- Data flow changes crossing trust boundaries
+- Infrastructure topology changes
+
+## When to Apply
+
+| Scenario | Apply? |
+| --- | --- |
+| New service or API endpoint | Yes |
+| New external integration | Yes |
+| Authentication or authorization changes | Yes |
+| Data flow crossing trust boundaries | Yes |
+| Internal refactoring with no boundary changes | No |
+| UI-only cosmetic changes | No |
+
+## Guidelines
+
+1. **Focus on trust boundaries, not implementation details.** Threats exist at boundaries where privilege levels change.
+2. **Mitigations must be verifiable.** Every mitigation maps to a test or verification method; unverifiable mitigations are theater.
+3. **Document accepted risks explicitly.** When a threat is acknowledged but not mitigated, record the rationale, severity, and conditions for revisiting.
+4. **Review when architecture changes.** The threat model is a living document that stays current with the system it describes.
+5. **Severity drives priority.** Critical and high-severity threats block implementation; medium and low are tracked and scheduled.
+6. **Threat models are collaborative.** Security analysis improves with input from architects, developers, and operations engineers.
+
+## Output
+STRIDE threat table with severity ratings, mitigation mapping, and verification methods. Explicitly list accepted risks with rationale. Be concise — table format; group by STRIDE category.
+
+## Integration
+
+- **Agent-Assisted Specification** — invoke during the Architecture Specification stage to identify security constraints before implementation
+- **Governance & Compliance** — threat documentation feeds compliance audit trails and security review records
+- **Accuracy Validation** — verify threat assessments against actual system state, not assumed state

package/skills/triage/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: triage
+description: >-
+  Investigate a bug, find its root cause, and write a portable triage record to
+  .dev-team-reports/triage/<slug>.md with a TDD fix plan. Use when the user
+  reports a bug and wants it triaged, says "triage this", "investigate and
+  write it up", or wants a hands-off bug investigation that produces an
+  actionable record.
+argument-hint: "<bug description or error message> [--pdf]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Agent
+---
+
+# Bug Triage
+
+Role: worker.
+
+Investigate a bug hands-off, find root cause, and write a TDD fix plan to a
+portable triage record at `.dev-team-reports/triage/<slug>.md` — no
+issue-tracker dependency.
+
+## Worker constraints
+
+1. Investigate and record; do not fix the bug.
+2. Find root cause before recording; do not record on symptoms alone — and do
+   not record an unverified, unrelated finding as if it were the root cause;
+   use the `unconfirmed` outcome instead.
+3. **Be concise.** The record is structured; chat is the `triage-record:` line
+   plus a one-line root-cause summary — not the full body.
+
+## Process
+
+### 1. Capture the Problem
+
+Get the bug description from the arguments or conversation. If no description is
+given, ask EXACTLY one question: `What's the problem you're seeing?` and stop.
+If a description is given, ask nothing — start investigating immediately.
+
+**Scoped exception:** if the description signals a cross-service or
+intermittent symptom (it names multiple repos/services, or uses language like
+"intermittent", "sometimes", or "inconsistently"), ask ONE additional targeted
+question before investigating: `Do you have any of the following: logs, a
+sample request/response pair, trace/audit IDs, or a config/pipeline export?`
+This is a narrow exception for that signal only — the "ask nothing" rule above
+still applies to every other description, and the no-description fallback
+question above is unchanged.
+
+Arguments: $ARGUMENTS
+
+### 2. Investigate
+
+Apply the systematic debugging protocol from `skills/systematic-debugging/SKILL.md`:
+
+1. **Reproduce**: Run the failing test or trigger the error
+2. **Investigate**: Trace data flow, check recent changes, find working reference code
+3. **Root cause**: Form and test a hypothesis
+
+Use the `dev_team_subagent` tool with `agent: "Explore"` to deeply investigate the codebase:
+related source files and dependencies, existing tests (covered vs missing),
+recent changes to affected files (`git log`), error handling in the code path,
+and similar patterns elsewhere that work correctly.
+
+**Boundary dead-end:** if static tracing (grep/`codegraph_explore`) returns
+zero hits for the relevant identifiers across all checked-out repos, name this
+explicitly as **"producer not located in scope"** — do not keep searching
+until an unrelated bug-shaped pattern turns up nearby. Carry this named
+outcome into the Verification Checkpoint (Step 4), which routes it to the
+`unconfirmed` outcome.
+
+### 3. Design TDD Fix Plan
+
+Create an ordered list of RED-GREEN cycles, each a vertical slice:
+
+- **RED**: A specific test capturing broken/missing behavior
+- **GREEN**: The minimal code change to make that test pass
+
+Tests verify behavior at the public interface, not implementation details.
+
+### 4. Verification Checkpoint
+
+**Hard gate — cannot be skipped implicitly.** Before writing a `confirmed`
+record, state in one sentence what concrete evidence (a log line, a
+reproduced failure, an observed value in the actual data path) ties the
+hypothesized cause to the *reported symptom*. A boundary dead-end from Step 2
+("producer not located in scope") counts as inadequate evidence.
+
+If that evidence exists, proceed to Step 5 with `confidence: confirmed`.
+If it does not, do not write a confirmed root-cause section — route to the
+`unconfirmed` outcome in Step 5 instead. There is no silent pass-through: a
+missing or hand-waved evidence statement means `unconfirmed`, not `confirmed`.
+
+### 5. Write the Triage Record
+
+**Resolve the slug** from the bug title/description with this 8-step algorithm:
+
+1. Lowercase.
+2. Strip non-ASCII characters.
+3. Replace spaces and underscores with hyphens.
+4. Strip every character that is not `[a-z0-9-]`.
+5. Collapse consecutive hyphens to one.
+6. If longer than 60 characters, truncate to 60, then cut back to the last
+   hyphen (so no word is split).
+7. Strip leading/trailing hyphens.
+8. If the result is empty, fall back to `triage-YYYYMMDD` (today's UTC date).
+
+**Resolve collisions:** if `.dev-team-reports/triage/<slug>.md` exists, append
+`-2`, `-3`, … up to `-99` until a free name is found. **Never overwrite** an
+existing record.
+
+**Write the file:** (see `knowledge/report-output-location.md` for the
+shared `.dev-team-reports/` convention this follows)
+
+```bash
+mkdir -p .dev-team-reports/triage/
+```
+
+If `.dev-team-reports/triage/` cannot be created or written (permission/read-only):
+report `Cannot write .dev-team-reports/triage/<slug>.md: <error>`, write the
+same content to a temp file (`tmp/triage-<slug>.md` or `$TMPDIR`), and print
+the full record content to chat so nothing is lost.
+
+When `--pdf` was passed and the record was written to disk, render **that
+resolved path** (the exact `<slug>` chosen after collision resolution) to a
+sibling PDF per `knowledge/report-pdf-integration.md` (additive; non-fatal if
+no engine):
+
+```bash
+sh "$CLAUDE_PLUGIN_ROOT/hooks/py.sh" "$CLAUDE_PLUGIN_ROOT/hooks/lib/report_pdf.py" .dev-team-reports/triage/<resolved-slug>.md
+```
+
+The record is YAML frontmatter followed by four sections. Three outcomes are
+possible, and they are mutually distinct — not variants of one another:
+
+- **`confirmed`** — the Verification Checkpoint (Step 4) found concrete
+  evidence tying the cause to the reported symptom. Full Root Cause Analysis
+  and TDD Fix Plan, no banner.
+- **`unconfirmed`** — a contributing factor was identified, but the
+  checkpoint found no evidence linking it to the reported symptom (including
+  a Step 2 boundary dead-end). Banner required; fix plan reframed as
+  addressing the contributing factor, not the confirmed cause.
+- **not determined** — no plausible cause was found at all. `## TDD Fix Plan`
+  is replaced with the fixed string below; there is no `confidence` field
+  distinction because there is nothing to mark as confirmed or unconfirmed.
+
+```markdown
+---
+id: <resolved-slug>
+created: <YYYY-MM-DDThh:mm:ssZ>
+status: open
+confidence: confirmed
+---
+
+# <concise bug title>
+
+## Problem
+
+- **Actual behavior**: [what happens]
+- **Expected behavior**: [what should happen]
+- **Reproduction**: [how to trigger it]
+
+## Root Cause Analysis
+
+[What code path is involved, why it fails, contributing factors. Describe
+modules and behaviors, not file paths — the record should survive refactors.]
+
+## TDD Fix Plan
+
+1. **RED**: Write a test that [expected behavior]
+   **GREEN**: [Minimal change to pass]
+
+2. **RED**: Write a test that [next behavior]
+   **GREEN**: [Minimal change to pass]
+
+**REFACTOR**: [Any cleanup after all tests pass]
+
+## Acceptance Criteria
+
+- [ ] Root cause is addressed (not just symptom)
+- [ ] All new tests pass
+- [ ] Existing tests still pass
+- [ ] No regressions introduced
+```
+
+**`confidence` field:** omitted/absent defaults to `confirmed` — no migration
+needed for historical triage records predating this schema. Set
+`confidence: unconfirmed`
+when the Verification Checkpoint routed here without evidence. When
+`unconfirmed`, `## Root Cause Analysis` must open with:
+
+```
+> **UNCONFIRMED** — contributing factor identified; not verified against the reported symptom.
+```
+
+and `## TDD Fix Plan` must explicitly frame the plan as addressing "the
+identified contributing factor," not the confirmed root cause.
+
+At least one RED/GREEN cycle is required. **If no root cause was determined,**
+the entire `## TDD Fix Plan` body is exactly:
+
+```
+Root cause not determined — manual investigation required
+```
+
+### 6. Present Results
+
+Print exactly two lines:
+
+1. `triage-record: .dev-team-reports/triage/<resolved-slug>.md` (the actual resolved path)
+2. A root-cause summary of at most 120 characters.
+
+Do not repeat the full record body in chat.