attckdigital/smith/smith-debug

SpecKit Debug Workflow

A diagnostic-only workflow that systematically investigates errors, failures, and unexpected behavior across the project's services. Produces a structured debug report stored in the relevant system's .specify/ folder. Does NOT modify code — the report becomes input to /smith-bugfix if a fix is warranted.

Arguments: $ARGUMENTS

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Marker before first append: the workflow-gate denies markerless Bash redirection, so cat >> "$SESSION" appends are blocked until the active-workflow marker exists. Create the marker (Phase 0 helper) FIRST, then write the invocation entry immediately after — do not log before the marker.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-debug <event>
 
**User Request:**
> <verbatim user message that triggered this action — capture the exact error description, symptoms, or question the user asked. Include any error messages they pasted.>
 
**Synthesized Input:** <brief summary of what's being investigated>
**Outcome:** <what happened>
**Artifacts:** <files created/modified>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — capture the verbatim user request AND the structured symptom description
2. After symptom capture — structured fields extracted
3. After triage — sub-agent findings summary
4. After diagnosis — root cause identified or hypotheses ranked
5. On completion — report path, user decision (bugfix/investigate/close)

Subagent Invocation Logging

Immediately before every Agent tool call in this workflow (especially the 4 triage agents in Phase 3), append a block to the session log. The Agent tool's return value does not expose subagent_type or model to the parent, so this is the only place that information can be captured.

### [HH:MM:SS] Subagent invoked: <description>
 
**Type:** <subagent_type or "general">
**Model:** <model override passed to Agent, or "inherited" if none>

HH:MM:SS here is UTC as well — date -u +%H:%M:%S, same rule as above. The subagent-vault-writeback.sh block that lands beside this one is hook-written and therefore already UTC; a local-clock invocation stamp would make a subagent appear to finish hours before it started.

After the Agent tool returns, the subagent-vault-writeback.sh hook automatically appends a matching "Subagent completed" block with metrics read from the sidechain transcript — do not duplicate that logging in the skill.

When to Use This

Use /smith-debug when:

• An error message or unexpected behavior needs investigation
• You're not sure what's broken or why
• Multiple services could be involved
• You want evidence before committing to a fix

Do NOT use when:

• The cause is already known and the fix is obvious — use /smith-bugfix directly
• You're building a new feature — use /smith-new

Natural Language Triggers

If the user says any of the following (or similar phrases), treat it as invoking this command:

• "debug this"
• "help me debug..."
• "can you investigate..."
• "I'm getting this error..."
• "why is X failing"
• "something is broken"
• "help me figure out why..."

When triggered by natural language, synthesize the conversation history into the symptom description and proceed as if that was passed as $ARGUMENTS.

Ledger Context (Optional)

If .smith/vault/ledger/ exists and contains non-empty files, load relevant Ledger sections to inform diagnosis. If the directory is missing, empty, or unreadable, skip silently — the Ledger is purely additive and never required.

1. Check: ls .smith/vault/ledger/*.md 2>/dev/null
2. If files exist, read the following sections (higher-confidence entries first, truncate at ~2000 tokens per file):

• .smith/vault/ledger/antipatterns.md (past failure modes — directly useful for narrowing hypotheses)
• .smith/vault/ledger/edge-cases.md (known weird states the system has hit before)
• .smith/vault/ledger/project-quirks.md (project-specific gotchas — e.g., "this service takes 30s to start, don't assume crash")
• .smith/vault/ledger/tool-preferences.md (which diagnostic tools/commands are known to work well in this project)

1. Use loaded entries as additional context during symptom capture, triage, and diagnosis. Especially use antipatterns.md to avoid re-investigating already-known failure modes from scratch, and project-quirks.md to skip false-positive theories. The Ledger informs judgment, it does not override evidence collected during this run.
2. Budget violation tracking: If any Ledger file was truncated (entries were dropped to fit within the ~2000 token budget per file), increment context_budget_violations in .smith/vault/ledger/.meta.json by 1. If .meta.json does not exist, create it from the default template first. This signal tells the reconciliation system that the Ledger is too large for the configured budget.

Phase 0: Activate Workflow Tracking

Before any file is written (debug reports, vault logs, etc.), create an active-workflow marker so the workflow-gate hook (PreToolUse) allows subsequent writes. Without this, even the debug-report Write at the end of Phase 5 would be denied. The workflow-gate hook exempts the shipped helper by basename (per spec/31-workflow-gate-bootstrap) so the bootstrap runs even when no marker exists yet:

SLUG=$(echo "${1:-debug}" | sed 's/[^a-zA-Z0-9._-]/-/g' | cut -c1-40)
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)
# Debug is read-only — no worktree, so use the current dir as the
# "worktree" sentinel. The helper still stamps the session log so
# workflow-summary attributes tokens correctly.
~/.smith/scripts/create-active-workflow.sh \
  --branch "debug-${SLUG}" \
  --workflow smith-debug \
  --slug "${SLUG}" \
  --worktree "$(pwd)"

(Falls back to scripts/create-active-workflow.sh in repo-dev layouts.)

The marker is cleared at the end of Phase 6 (Decision Gate) regardless of which option the user picks. Use the shipped helper so this works under a Bash(rm:*) deny rule:

.specify/scripts/bash/clear-active-workflow.sh "debug-${SLUG}"

Phase 1: Symptom Capture (Interactive if needed)

Extract or ask for these structured fields from the user's description:

Interactive prompting

If the user's initial description is missing 2+ of these fields, ask a focused set of clarifying questions BEFORE proceeding. Present them as a numbered list the user can answer quickly:

To investigate this efficiently, I need a few more details:
 
[1] What exactly were you doing when this happened? (e.g., which button, command, or workflow)
[2] Does this happen every time, or only sometimes?
[3] Were any other operations running at the same time?
[4] When did this start? (always been this way, or recent change?)

Only ask for what's actually missing. If the description already covers 3+ fields, proceed directly — don't slow the user down with unnecessary questions.

If ALL fields are present in the initial description or $ARGUMENTS: skip prompting entirely and proceed to Phase 2.

Phase 2: System Detection

Determine which of this project's system(s) this debug session relates to. Derive the system list from the current project — never assume a fixed set of systems.

1. Discover the project's systems in this priority order:

• If .smith/index/manifest.md exists, read it (and .smith/index/systems/) for the authoritative service-to-system mapping. Prefer /smith-navigate "<symptom>" if available — it returns the relevant system(s) for a task description directly.
• Otherwise, list .specify/systems/*/ to enumerate the project's systems and read each spec.md frontmatter (paths:) and body to understand what each covers.
• If neither exists, treat the project as un-systematized: use a single default system folder (.specify/) and skip system routing.

1. Map the symptom to systems: match the affected service(s), ports, file paths, or component names from Phase 1 against the discovered systems. Use paths: frontmatter and service/port references in each system's spec.md to route.

1. If ambiguous: pick the most likely primary system and note secondary systems.

1. Set the report path:

`` .specify/systems/<primary-system>/debug/debug-YYYY-MM-DD-<slug>.md ` Create the debug/` directory if it doesn't exist.

Phase 3: Automated Triage (Parallel Sub-agents)

Launch up to 4 diagnostic sub-agents in parallel. Each is read-only — no code modifications.

3.1 Infrastructure Health Agent

Model: haiku Task: Check the health of all services and resource usage.

- Run: docker compose ps
- Run: bash scripts/health-check.sh
- Run: docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}"
- Check if affected service(s) are running and healthy
- Check port availability for affected services
- Check Colima resource allocation: colima status
- Report: which services are up/down, resource pressure, port conflicts

3.2 Log Analysis Agent

Model: haiku Task: Search service logs for the error and surrounding context.

- Run: docker compose logs <affected-service> --tail 200 --timestamps
- Run: docker compose logs <upstream-dependencies> --tail 100 --timestamps
- Grep logs for the exact error message
- Grep for related patterns (connection refused, timeout, OOM, restart)
- Look for temporal correlation with other service errors
- Report: relevant log excerpts, error frequency, first occurrence timestamp

3.3 Dependency Trace Agent

Model: sonnet Task: Map the request path and check each hop.

- Identify the full request chain for the failing operation
  (e.g., UI → Express → FastAPI → Ollama → Qdrant)
- For each hop:
  - Is the upstream service reachable? (curl health endpoints)
  - Is the connection using the right host/port?
  - Are there resource contention issues? (shared Ollama, shared PG connections)
- Check docker-compose.yml for network configuration
- Check environment variables for correct service URLs
- Report: which hop fails, why, and what the expected vs actual behavior is