---
model: sonnet
---

# /tas-debug $ARGUMENTS

Role: SE - Software Engineer
Debug and resolve build/runtime/functional errors for an already-implemented feature or stack.
Use when: feature is coded but broken, server crashes on start, browser shows errors, tests fail after merge.
Differs from /tas-fix: runs full build-debug loop (start server → capture logs → browser check → auto-resolve up to N times).
Differs from /tas-dev Step 3.5: standalone — no implementation phase, targets existing code.

## Stack Detection
Read `.tas/rules/common/stack-detection.md`.

## Actions

### Step 1 — Identify target

`$ARGUMENTS` may be:
- Feature ID (e.g. `TAS-042`) → read Feature file + Technical file from `docs/features/`
- Stack directory path (e.g. `apps/web`) → skip Feature files, infer stack from contents
- Error message / stack trace (no ID) → ask user: "Which stack/dir is broken?"
- Empty → read `project-status.yaml`, find features with `status: In Development`. If multiple, list for user to choose.

From target, determine:
- `stack` — detected from Feature frontmatter OR inferred from `package.json` / `*.csproj` / `*.py` / `*.sln` in dir
- `working_dir` — root dir for that stack's server process
- `changed_files` — if Feature file exists: read Technical file `## File Changes`. Else: `git diff --name-only HEAD` in working_dir.
- `ac_list` — if Feature file exists: extract AC lines (Given/When/Then). Else: empty (skip functional check).

### Step 1.5 — Architecture trace (if `docs/architecture-map.yaml` exists)

Right after identifying the target, locate the fault in the architecture using the spine — this refines `working_dir`, `changed_files`, and the suspect layer before any probing. Follow the **Trace procedure** in `.tas/rules/common/architecture-map.md` (section B):
- Symptom anchor (endpoint / screen / event / log `MOD-id` / stack-trace file) → MOD via `provides` or `code_anchor` prefix-match.
- MOD → `built_by` Feature(s) → read that Feature-Technical (Logic Flow / File Changes / AC) to judge whether the solution itself is flawed.
- Walk `depends_on` (downstream cause) and its inverse (dependents / blast radius).
- Outcome: a one-sentence root-cause hypothesis naming the suspect MOD/layer, and whether this is a code defect (continue) or a design flaw (stop → `/tas-sad` / `/tas-adr`).

Skip if the map does not exist; fall back to the triage ladder alone.

### Step 2 — Snapshot current error (optional fast-path)

If `$ARGUMENTS` contains an error message or stack trace:
- Pass directly to `build-resolver` agent as pre-diagnosis context (include the Step 1.5 hypothesis if found)
- Apply returned fix first, then enter build-debug loop at attempt 1

If no error provided: go straight to loop.

### Step 2.5 — Triage Ladder (before loop)

Enumerate hypotheses for the reported symptom. Probe cheapest first. Stop at first level that produces divergence from expected.

For "page broken" symptom:
- **L1. HTTP status** — `curl -sI {url}` (headers only, ~5 lines)
- **L2. Server log** — already streaming from loop; check last 20 lines
- **L3. HTML snapshot** — `curl -s {url} > .tas/tmp/snap.html` (single fetch, reuse for L4)
- **L4. Section presence** — Grep against `snap.html` for expected markers (titles, ids, data attrs)
- **L5. Template/render code** — `Read` with `offset` + `limit` at suspect range (never full file unless ≤ 80 lines)

For "API broken" symptom: L1 → L2 → curl JSON body → Grep handler → Read handler range.

For "test failing": jump to error line in test output → Grep target symbol → Read narrow range.

**Rules**:
- One snapshot per URL per session. Re-Grep the cached `snap.html`, do not re-fetch.
- Drop levels above the divergence point — do not probe further once cause located.

### Step 3 — Build & Debug Loop

Read `.tas/rules/common/build-debug-loop.md`. Follow loop protocol exactly.

```
max_attempts = tas.yaml[build_debug_attempts] ?? 3
```

Run loop for each stack identified in Step 1.
If multiple stacks (monorepo): run sequentially, stack order from Technical Plan (or alphabetical if no plan).

**build-resolver call context**: stack, command, attempt N/max, exit code, ≤20-line error neighborhood (head+tail of the last 50 stdout+stderr — per build-resolver's input cap, do not dump the full 50), browser errors (if any), AC text (if functional check), changed_files list.

### Step 4 — Wrap up

**Before anything else: confirm Tear Down ran.** Loop protocol mandates kill_server() on all exit paths. Verify no dev server PID still alive (check port / process list). If orphan detected → kill via Tear Down snippet from `build-debug-loop.md` before logging.

**If loop PASSED:**
- Append `## Build Debug Log` to Technical file (or create standalone log file `docs/debug/{FEATURE_ID}-debug-{date}.md` if no Technical file)
- **SAD Impact Heuristic** — read `.tas/rules/common/sad-impact.md` "Quick Heuristic". Grep changed files for trigger patterns (deps add, ENV add, Dockerfile EXPOSE/ENV, migrations, IaC, CI, new top-level dirs).
  - **Hit & target = Feature ID:** auto-invoke `/tas-sad "Feature-{NNN}: {summary of triggers hit}" --autonomous={mode}` (where `{mode}` = `true` if this `/tas-debug` run was itself invoked with `--autonomous=true`, else `false`); verify `Feature-{NNN}` in Changelog before wrap.
  - **Hit & target = standalone dir (no Feature):** STOP wrap, surface: "Debug fix touches SAD trigger ({signal}). Re-run as `/tas-bug` or run `/tas-sad` manually before committing."
  - **No hit:** continue normally.
- Output commit message: `fix: resolve {stack} build/runtime errors for {Feature ID or dir}`
- Suggest: "Run `/tas-functest {Feature ID}` to verify AC end-to-end."
- If fix touched ≥ 3 files or changed architecture: suggest `/tas-review {Feature ID}` for post-fix review.

**If loop FAILED (max attempts exceeded, or aborted by the no-divergence guard):**
- Output warning block (format from `build-debug-loop.md`)
- Do NOT commit partial fixes
- **Surface uncommitted changes:** any build-resolver fixes applied during the loop remain in the working tree (and may include a SAD trigger — deps/ENV/migration). List them (`git diff --name-only`) and recommend reviewing/reverting before a re-attempt; the SAD heuristic above only runs on the PASS path.
- Suggest: `/tas-bug` if issue is severe enough for full tracking.

## Principles
- DO NOT implement new features — only fix what's broken
- DO NOT read more than 5 files outside the broken stack without user confirmation
- DO NOT read sibling working files until root-cause hypothesis is named (one sentence stating which layer is suspect)
- DO NOT read migration files when a D1/SQL query result answers the same question — query first, read schema only if query result is unexpected
- Read full file only when ≤ 80 lines OR Grep has already pinpointed a line range — otherwise use `offset` + `limit`
- Fix at root cause — do not patch symptoms
- If fix requires architectural change → stop, surface to user, suggest `/tas-adr`
- If changed files match SAD Impact Heuristic → auto-invoke `/tas-sad` (Feature target) or escalate to `/tas-bug` (standalone target)

## Final Step — Token Log

Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to Feature file (if exists) or debug log file.