@techierathore/techieflow 1.0.2 → 1.0.4

package/.claude/commands/TechieFlow/tasks/triage-issues.md

@@ -1,157 +1,16 @@
 # triage-issues
 
-The **ANALYZE-ONLY** front door for bugs a human found by running the app — UAT feedback, production reports, an owner test session. Flow-master reproduces each reported issue, triages it to its owning screen + REQ, and delivers **documentation, not code**: checklist updates (demotions + new bug REQ rows), an optional scoped regression re-verify, DevGuide known-issues notes, and a PROJECT-STATUS refresh whose next-command points at the fix. **It NEVER changes source code and NEVER spawns builder sub-agents.** Fixing is a separate, later decision the owner makes by running `*fix-issues` (or `*build-phase`).
+`*triage-issues {App} {evidence} [verify]` is the analyse-only front door for bugs a person found by running the application: UAT feedback, a production report, an owner test session. The evidence is a folder of screenshots with an optional notes file, a written list, or both. The deliverable is the checklist and the telemetry, never code: nothing under `src/`, `source/` or `tests/` changes, and no builder is spawned. Fixing is the owner's next decision, `*fix-issues`. It honours YOLO.
 
-## Why this exists
+First: `bash .tfcore/utils/tf-phase.sh start triage-issues {App}` prints the start time; keep it.
 
-`*fix-issues` fixes — that is its deliverable. When the owner says "analyze these UAT bugs, re-verify the other features, and update the checklist", they want a **plan and a paper trail** — which REQs regressed, what is new, what still passes — WITHOUT an agent charging ahead and editing code nobody asked it to touch (that happened: AstroLyfe UAT, 2026-07-16 — an "analyze and log" request was routed into fixing). After this task runs, the checklist + PROJECT-STATUS fully describe the bugs, and NOTHING in `src/` or `tests/` has moved.
+## Steps
 
-## Inputs
-
-- `{AppName}` (required; or resolve from `core-config.yaml`).
-- `{Evidence}` — one or both of:
-  - a **folder** of screenshots (+ optional description file `bugs.md` / `README.md` / `notes.txt`) — the same evidence channel `*fix-issues` uses; and/or
-  - a **written bug list** — chat text or a file path (UAT/production reports often arrive as prose).
-  If neither is given, ask once for the folder path or the list.
-- `[verify]` (optional literal) — after logging, ALSO execute a scoped regression re-verify (§5). Without it, the verifier is not run at all.
-
-## HARD SCOPE RULE — read this before anything else
-
-**This task is read-only on the application.** You may boot and drive the app, but you MUST NOT edit anything under `src/` or `tests/`, MUST NOT spawn `/trblazeui`, `/techierag`, or any fixer sub-agent, and MUST NOT "quickly fix" anything you find — however obvious the one-liner. The only files you write: `docs/{AppName}-Checklist.md`, the DevGuide's known-issues lines, `PROJECT-STATUS.md` + `.html`, and (in `verify` mode) whatever an executed verify-phase legitimately writes. If the owner asks mid-run for a fix, that is a NEW command (`*fix-issues`) — finish the triage deliverables first, then say so.
-
-## SEQUENTIAL Execution
-
-### 0. Stamp the start time
-
-`date -u +%Y-%m-%dT%H:%M:%SZ` — keep it. It is this run's `started` and `run_id` for §6a.
-
-### 1. Ingest the evidence
-
-- If a folder was given: list it, **read every screenshot** (vision) and the description file if present.
-- If a written list was given: extract one issue per distinct symptom, keeping the owner's wording in the record.
-- Build a working list: `{ id, screen/route guess, role guess, symptom, evidence (image path or quoted words), kind-guess }` — kinds as in fix-issues: `layout`, `render-empty`, `data/logic`, `rag`. Final classification happens after repro (§3).
-
-### 2. Boot the app (per `_smoke-test-policy.md` + `verify-phase.md §Local-only`)
-
-- Boot it yourself via the build-invocation-ladder; dependent services in dependency order. "Can't run on Linux / it's MAUI / needs a GUI" are BANNED excuses; escalate per `verify-phase.md §3a`. Never propose a cloud deploy.
-- Resolve a test login from `docs/{AppName}-UsageGuide.md` / the DB — never auto-create a random user.
-
-### 3. Reproduce and triage each issue
-
-For each issue: log in as the relevant role, navigate to the screen, and **reproduce the symptom**. Apply the data-render gate (`verify-phase.md §4a`) and the visual-truth gate (`§4b`) OBSERVATIONALLY, settle the issue's kind from what you see, and map it to the owning screen + `REQ-*` in `docs/{AppName}-Checklist.md` (DevGuide screen→REQ map). An issue that does not reproduce is recorded as `could-not-reproduce` with what you tried — never guessed at.
-
-Echo a triage table — same shape as fix-issues §3, but the last column is the **checklist action**, not a builder:
-```
-Issue 1 → REQ-UI-007 (Dashboard) — kind: layout (KPI cards overlap chart)  → demote to Needs re-verify
-Issue 2 → REQ-FN-014 (Clients)   — kind: render-empty (16 count, 0 rows)   → demote to Needs re-verify
-Issue 3 → (no owning REQ — export button missing)                          → NEW row REQ-FN-021 (Planned)
-Issue 4 → REQ-RAG-003 (Assistant)— could-not-reproduce (answer rendered OK) → dated Remark + owner question
-```
-
-### 4. Log the bugs — the checklist IS the deliverable
-
-For each reproduced issue, in `docs/{AppName}-Checklist.md`:
-
-- **Regression of an existing REQ** (the broken behaviour is inside a REQ's scope, whatever its current status): set Status → `Needs re-verify`, adjust % per the guide, and add a dated Remark — `⚠ UAT bug {today}: {symptom} (evidence: {path or "owner report"}; kind: {kind})` (use `⚠ prod bug` for production reports). Demotions are always allowed — guard-verify never blocks them. **NEVER write `Verified` from this task.**
-- **Defect with no owning REQ** (behaviour that was never specified): append a NEW row — next free ID in the right prefix — Status `Planned`, Remark `logged from UAT {today}`, plus a detail bullet (with its `<a id="d-req-…">` anchor) in the matching section stating the ACCEPTANCE that would close it. If it is genuinely NEW SCOPE (a feature request, not a defect), still log the row but flag `*amend-docs` in the report — do not invent BRD text here.
-- **Could-not-reproduce**: a dated Remark on the nearest REQ (no status change) + a question for the owner in the report.
-
-### 5. Optional regression re-verify (`verify` argument only)
-
-The owner often wants "and check the rest still works". With `verify`: read `.tfcore/tasks/verify-phase.md` and **EXECUTE it inline** (skip its §0 question — scope is known), scoped to (a) the demoted REQs' siblings — other REQs owning the same screens/services — and (b) any scope the owner named. This is a real verify-phase run: it writes the `docs/.last-verify.json` ledger and may legitimately write `Verified` / `FAIL` verdicts. Without `verify`, skip this section entirely — do not "informally" re-check other features and write verdicts from it.
-
-### 6. Update the docs (status gate)
-
-- **DevGuide:** add/refresh the affected screens' Known-issues lines (cite the evidence screenshot). If a screen is not in the DevGuide yet, note it for `*devguide {AppName} --update` — do not run a full devguide pass here.
-- **PROJECT-STATUS (FINAL GATE, per `_status-update-gate.md`):** overwrite in place, `.md` AND `.html`. Phase reflects reality (open bug rows pull the project back to Build/Verify per the ladder). **Next command:** the bug rows just logged are build-tier work whose front door is **`*fix-issues {AppName} {Folder}`** — point there, naming the REQ IDs (fall back to `*build-phase {AppName}` when there is no evidence folder to hand it). Add a Verification-log row ONLY if §5 ran — triage by itself is not a verify pass.
-- **Never run git.**
-
-### 6a. Emit telemetry — this is where ESCAPE RATE comes from
-
-Doctrine: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §3.
-
-A bug reaching this task means **every gate missed it** — it got past acceptance, data-render, visual-truth and standards, and a human found it in UAT or production. That fact exists nowhere else in the framework, and it is the only way escape rate can be computed. Emit it.
-
-**One `gates.jsonl` record per REQ you demoted or newly logged in §4**, with `gate:"escaped"`:
-
-```bash
-ATT=$(bash .tfcore/utils/tf-emit.sh --next-attempt REQ-UI-009)
-cat <<JSON | bash .tfcore/utils/tf-emit.sh gates
-{"kind":"gate","app":"{AppName}","run_id":"<the run start timestamp>",
- "req_id":"REQ-UI-009","req_class":"UI","attempt":$ATT,"verdict":"Needs re-verify",
- "gate":"escaped","gates_run":[],"failure_class":"overlap","prior_verdict":"Verified"}
-JSON
-```
-
-- `gate` is **always `"escaped"`** here. Never name a real gate — none of them fired; that is the entire finding.
-- `gates_run` is `[]` — this task runs no gates. (Records written by the §5 verify pass are the verifier's, emitted by verify-phase §6a with real gate names. Do not duplicate them.)
-- `prior_verdict` is the Status you demoted **from** — `Verified` there is the strongest possible signal and must be recorded faithfully.
-- `failure_class` from the closed enum only. **Never the symptom text** — the symptom belongs in the checklist Remark, never in telemetry (constraint 7).
-- **Could-not-reproduce → emit nothing.** No defect was established; a record would inflate the escape rate with a non-event.
-- New `Planned` rows for never-specified behaviour: emit with `verdict:"FAIL"`, `prior_verdict:null` — the gap escaped just as surely, it simply had no REQ to escape from.
-
-**Then one `misses.jsonl` record per reproduced issue** (SCHEMA.md §5.5). The `escaped` gate record above says *no gate caught it*; the miss record says *what was missed and which phase let it through* — the two answer different questions and both are wanted.
-
-```bash
-MID=$(bash .tfcore/utils/tf-emit.sh --next-miss-id)
-cat <<JSON | bash .tfcore/utils/tf-emit.sh misses
-{"kind":"miss","miss_id":"$MID","req_id":"REQ-UI-009","req_class":"UI",
- "miss_class":"regression","artifact":"src","severity":"blocker",
- "why_missed":"insufficient-verify-method",
- "origin_phase":"build-phase","origin_agent":"trblazeui",
- "origin_run_id":"<started of the run that last touched this REQ, from runs.jsonl>",
- "found_by":"owner","found_phase":"triage-issues","found_gate":null,
- "found_run_id":"<this run's start>","failure_class":"overlap"}
-JSON
-```
-
-- **`found_by`** is `"owner"` for a UAT / owner test session and `"production"` for a live report. Nothing else — this field is what separates an in-cycle failure from a true escape, and it is the whole reason the record is worth writing.
-- **`found_gate` is `null`.** No gate fired; that is the finding.
-- **`why_missed` is NOT optional here.** Every record this task writes is an escape — it got past every gate and a human found it — so *why nothing caught it* is the entire value of the record, and the report warns when it is absent. Answer it from what you observed reproducing the bug: `missing-checklist-item` (no acceptance covered this behaviour), `insufficient-verify-method` (acceptance existed but no gate could have caught this), `code-audit-limitation` (the screen was never runtime-observable), `ambiguous-acceptance`, `dependency-not-declared`. This is the field that tightens the gates for next time.
-- **Run the `--open-miss` collapse check first**, exactly as verify-phase does: if this REQ already has an open miss of the same `miss_class`, the owner has found the same defect the gates already know about — emit nothing.
-- **A defect with no owning REQ** (a new `Planned` row in §4) is `req_id:null`, `miss_class:"unspecified-gap"`, `artifact:"brd"`. That combination is the single most valuable record in this stream: **it is a design miss, caught by a human, months after the phase that made it.**
-- **Could-not-reproduce → emit nothing**, for the same reason no `gates` record is written: no defect was established.
-
-Then one `runs.jsonl` record:
-
-```bash
-cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
-{"kind":"run","app":"{AppName}","cmd":"triage-issues","mode":null,
- "started":"<start>","ended":"<now>","duration_s":<n>,
- "reqs_touched":["REQ-UI-009"],"reqs_count":1,
- "subagents":[],"files_written":<n>,"build_result":"not-run"}
-JSON
-```
-
-`build_result` is `"not-run"` unless you actually built something (you did not — this task never touches code). **Telemetry has no veto:** a failed emit changes nothing and is not worth reporting.
-
-### 7. HALT — report (and DO NOT fix)
-
-```
-# Triage — {AppName}
-Evidence: {folder and/or written list} ({S} screenshots, {n} reported issues)
-Reproduced: {r} → {d} REQs demoted to Needs re-verify, {p} new Planned rows | Could-not-reproduce: {x} (questions below)
-Regression re-verify: {ran on <scope> — <pass>/<fail> | not requested}
-Docs: checklist + DevGuide known-issues + PROJECT-STATUS (.md + .html) updated
-NOTHING in src/ or tests/ was changed — fixing was not requested.
-Next: /TechieFlow:agents:flow-master *fix-issues {AppName} {Folder}   (OpenCode: /flow-master)   (targets: {REQ IDs})
-```
-
-## Hard rules
-
-- **Docs are the deliverable; code is untouchable.** No `src/`/`tests/` edits, no builder sub-agents, no "obvious one-liner" fixes. If you changed a source file, this task FAILED.
-- **Never write `Verified` from triage.** Demote freely; promotion happens only through the §5 EXECUTED verify-phase (which writes its own run ledger).
-- **Triage from what you OBSERVE** — reproduce live before logging; `could-not-reproduce` is a valid answer, never a licence to guess.
-- **Boot it yourself**; documented test users only; never auto-create one.
-- **Status gate is the last action** — PROJECT-STATUS `.md` AND `.html`; next command = the fix pointer with REQ IDs. Never run git.
-
-## Output Checklist
-
-- [ ] Evidence ingested — screenshots vision-read and/or prose parsed; issue list built
-- [ ] App booted (incl. dependent services); documented test user used
-- [ ] Every issue reproduced (or recorded could-not-reproduce) and mapped to screen + REQ — triage table echoed
-- [ ] Checklist updated — demotions with dated `⚠ UAT bug` remarks; new `Planned` rows with acceptance detail bullets
-- [ ] `verify` arg honoured (scoped verify-phase EXECUTED, ledger written) — or verifier untouched
-- [ ] DevGuide known-issues refreshed; PROJECT-STATUS `.md` + `.html` updated; next command = `*fix-issues` pointer with REQ IDs
-- [ ] ZERO source/test files modified; no builder sub-agent spawned
-- [ ] `gates.jsonl` record with `gate:"escaped"` emitted per demoted/new REQ, + one `misses.jsonl` `miss` per reproduced issue (`found_by:"owner"`/`"production"`, collapse-checked), + one `runs.jsonl` record (§6a)
+1. Read every screenshot and the notes; from a written list take one issue per symptom in the reporter's words. Build the issue list: screen, role, symptom, evidence path, a first guess of kind (`layout`, `render-empty`, `data-logic`, `rag`).
+2. `bash .tfcore/utils/tf-verify-boot.sh start` boots the application (dependent services first, from their own configuration). Sign in as a UsageGuide test user (`.tfcore/tasks/_smoke-test-policy.md`). NONE means the issues are logged from the evidence alone and the report says the app was not booted.
+3. Reproduce each issue on its screen; `bash .tfcore/utils/tf-verify-screens.sh --screen <name>=<route> … --base <url>` gives the render and visual evidence and a screenshot. Settle the kind from what you see and map the issue to its row in the checklist (the acceptance line's screen; the DevGuide's screen list). Print the triage table: issue, row, kind, action.
+4. Log each issue with `bash .tfcore/utils/tf-triage.sh {App} …`: `demote <REQ> "<symptom>" --kind … --evidence <path>` for a defect inside a row's scope, whatever its status; `new "<title>" "<When … on <screen>, then …>" --section "<screen>"` for a defect no row covers (a Not Started row with `BRD-pending`; new scope rather than a defect is still logged, and the report names `*amend-docs`); `note <REQ> "<what was tried>"` when it could not be reproduced. `--source production` for a live report. Whose gap it was is recorded as `--sort` (the four questions of `.tfcore/tasks/log-miss.md` step 1); without it a demoted row is `weak-check` (its line existed and the check let it through) and a new row is `spec`.
+5. With `verify`: execute `.tfcore/tasks/verify-phase.md` inline, scoped to the demoted rows' siblings on the same screens and any scope the owner named. Without it, the verifier does not run and nothing is re-checked informally.
+6. `bash .tfcore/utils/tf-verify-boot.sh stop`, then `bash .tfcore/utils/tf-triage.sh {App} close --started <the step-0 time>`: one escaped gate record per row (no check caught it), one miss per row in the reporter's words with the discovery cost, the run record, and a warning plus a miss if any code file changed during the run.
+7. Run the status gate (`.tfcore/tasks/_status-update-gate.md`); the run record is the one step 6 wrote. The next command is `*fix-issues {App} {evidence}` naming the rows.
+8. Report: evidence read, issues reproduced and logged (rows demoted, rows added), could-not-reproduce with the question for the owner, the verify scope if it ran, "no code changed", and the next command.