attckdigital/smith/smith-bugfix

SpecKit Bugfix Workflow

A streamlined alternative to /smith-new for bugs, small changes, and trivial fixes that don't require requirements gathering, planning, or a questions gate. Runs fully autonomously from invocation to merged PR.

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 1 step 2 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-bugfix <event>
 
**User Request:**
> <verbatim user message that triggered this action — capture the exact words the user typed describing the bug or fix needed. For natural language triggers like "fix this", include the preceding context that describes what's broken.>
 
**Synthesized Input:** <brief summary of the fix being applied>
**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 synthesized bug description
2. After branch created — branch name
3. After fix applied — files modified, brief description of the fix
4. After tests — pass/fail summary
5. After specs updated — which specs were updated
6. On completion — PR number, merge status, success/failure

Subagent Invocation Logging

Immediately before every Agent tool call in this workflow, 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 (vs /smith-new)

Use /smith-bugfix when:

• Fixing a bug or broken behavior
• Making a small, well-defined change (rename, restyle, config tweak)
• The change is scoped to 1-3 files with no design ambiguity

Upgrade to /smith-new if during implementation you discover:

• Multiple systems need coordinated changes
• Design decisions require user input
• The scope is larger than initially thought

If upgrading: STOP, tell the user, and offer to switch to /smith-new with the context gathered so far.

Natural Language Triggers

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

• "fix this"
• "bugfix this"
• "quick fix for..."
• "patch this"
• "just fix..."

When triggered by natural language, synthesize the conversation history into a concise bug/fix description and proceed as if that description was passed as $ARGUMENTS.

Phase 1: Worktree Setup

Every bugfix always runs in an isolated git worktree branched from the configured base branch (origin/$BASE_BRANCH, defaulting to origin/main). The user's current working directory and branch are NEVER touched, and concurrent Smith sessions cannot collide on the shared working tree. There is no "switch to base / stash / cancel" branching logic — the worktree is mandatory.

1. Generate fix slug (2-4 words) from the fix description. Store as $SLUG. Derive:

• BRANCH=fix/$SLUG
• WORKTREE_PATH=/tmp/smith-bugfix-$SLUG
• PRIMARY_REPO=<current working directory — capture before entering the worktree>

1. Resolve the configured base branch, then fetch it (does NOT change the user's current branch). Smith reads the project's integration branch from the constitution; it falls back to main when unconfigured:

``bash BASE_BRANCH=$(.specify/scripts/bash/get-base-branch.sh) git fetch origin "$BASE_BRANCH" ``

1. Activate workflow tracking — invoke the shipped helper to create the per-branch marker. The workflow-gate hook (PR #20) exempts this exact helper by basename so the bootstrap runs even when no marker exists yet (per spec/31-workflow-gate-bootstrap). The helper also stamps the current session log with a workflow-start line so workflow-summary.sh --totals-only can attribute tokens to this workflow:

``bash ~/.smith/scripts/create-active-workflow.sh \ --branch "$BRANCH" \ --workflow smith-bugfix \ --slug "$SLUG" \ --worktree "$WORKTREE_PATH" ` (Falls back to scripts/create-active-workflow.sh in repo-dev layouts.) The helper exits 3 if a marker already exists for this branch under a different workflow type. The marker path is derived from --branch alone (<safe-branch>.yaml); --slug only fills the feature: field *inside* the file, so retrying with a different slug writes the identical path and exits 3 again. The remedies are to use a different branch, or — if the existing marker is stale — to clear it with clear-active-workflow.sh and retry. The marker is cleared by the Workflow Cleanup step at the end via clear-active-workflow.sh`.

1. Create the worktree with the fix branch from the configured base branch (`origin/$BASE_BRANCH`):

``bash git worktree add "$WORKTREE_PATH" -b "$BRANCH" "origin/$BASE_BRANCH" ` The user's current branch is completely unaffected. They can be on main`, a feature branch, or a detached HEAD — this workflow will not interfere.

1. Copy `.env` to the worktree (only if one exists in the primary repo and the fix might touch services that read it):

``bash [ -f .env ] && cp .env "$WORKTREE_PATH/.env" ``

1. All subsequent phases (2-7) run inside `$WORKTREE_PATH`. Use cd "$WORKTREE_PATH" for the first command, then keep every subsequent command scoped to that directory via absolute paths or explicit cd. Do NOT cd back to the primary repo until Phase 7.3 (merge) — gh pr merge must run from the primary repo to avoid "main already checked out" errors.

On failure before merge: preserve the worktree for debugging and log its path in the session log. Do NOT auto-remove it. Leave the active-workflow yaml in place so the user knows the session is still holding that branch.

Ledger Context (Optional)

If .smith/vault/ledger/ exists and contains non-empty files, load relevant Ledger sections to inform this bugfix. 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
• .smith/vault/ledger/edge-cases.md

1. Use loaded antipatterns and edge cases as additional context to avoid known failure modes. The Ledger informs judgment, it does not override spec/plan/constitution.
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 2: Spec Cross-Reference

Before writing any code, check existing specs for context and conflicts.

1. Identify affected systems from the fix description and map to spec directories:

• services/command-center/ → specs/system-15-command-center/spec.md
• services/email-pipeline/ → specs/system-03-email-archive-contact-graph/spec.md
• services/sentiment-engine/ → specs/sentiment-engine/spec.md
• services/communication-triage/ → specs/system-05-communication-triage/spec.md
• services/voice-training/ → specs/system-04-personal-voice/spec.md
• docker-compose.yml → specs/system-01-core-infrastructure/spec.md
• Other mappings as discovered from specs/*/spec.md content

1. Read relevant spec.md files and check:

• Is the "broken" behavior actually intentional per the spec?
• Are there related requirements that could be affected by this fix?
• Are there any conflicting specs?

1. If a conflict is found: STOP the workflow and alert the user. Explain the conflict and ask how to proceed. This is the ONLY point where the workflow may pause.

1. If no conflicts: Continue silently.

Ledger-Informed Auto-Retry

If the bugfix execution fails, check config for auto-retry:

1. Read .smith/config.json — check ledger.auto_retry and ledger.max_retries
2. If auto_retry is false (default) or config is missing, do NOT retry — fail normally
3. If auto_retry is true:

a. Re-read .smith/vault/ledger/antipatterns.md to get the latest failure patterns b. Analyze the failure against known antipatterns to adjust the approach c. Retry the fix with the adjusted approach d. Repeat up to max_retries times (default: 2), re-reading antipatterns before each attempt e. If all retries exhausted, fail with a summary of all attempts

1. Each retry attempt is logged to the session log with attempt number and adjusted approach

Phase 3: Implement the Fix

1. Read the affected files to understand current behavior
2. Implement the fix — keep changes minimal and focused. When the fix adds

or changes code, keep that code clean:

• Small, single-responsibility functions and files; one clear reason to change.
• Intention-revealing names (avoid data, temp, handler, util when a

meaningful name exists).

• Guard clauses over deep nesting; keep control flow shallow.
• Separation of concerns — keep I/O, business rules, and persistence in

distinct units.

• No dead code, commented-out blocks, or duplicated logic.
• Reuse existing components over recreating them — check for an existing

module/service/utility that already does it before writing something new.

This does NOT license refactoring untouched surrounding code — see the constraints below.

1. Do NOT:

• Refactor surrounding code
• Add features beyond the fix
• Modify unrelated files
• Add unnecessary abstractions

Phase 3.5: Update .meta Descriptions for Touched Methods

After every Write or Edit to a source file in this fix, refresh the file's .meta description layer to reflect the new or changed methods. This step is cheap because Claude already has the source open and parsed in working memory — it does NOT regenerate descriptions for untouched methods, and it does NOT call any LLM from the save hook (the save hook remains LLM-free per data-model.md §3.2). Per data-model.md §4 and research.md §6.