Skip to content

vt-c-quickfix

Apply a quick-fix with automatic audit trail. For small, self-contained changes (typos, label corrections, minor UI tweaks) that do not warrant a full spec workflow. Creates an audit file in intake/quick-fixes/, branches, applies the fix, and optionally creates a PR.

Plugin: core-standards
Category: Other
Command: /vt-c-quickfix

/vt-c-quickfix

Quick-Fix Intake Path with Audit Trail (SPEC-133).

Invoke as: /vt-c-quickfix "Fix typo in dashboard heading"

When to Use

  • Small, self-contained changes (typos, label corrections, color tweaks, copy fixes)
  • Change is obvious and unambiguous — no design decision required
  • Fix takes less than 30 minutes to implement
  • No risk of breaking other features

When NOT to use: if the fix requires architectural decisions, affects multiple systems, or has unknowns → use /vt-c-spec-from-requirements instead.

Execution

Step 0.5: Project Registration Check

Run the shared registration check — single source of truth. Do NOT inline the logic here (duplicating it re-introduces the cross-copy drift SPEC-150 removed):

bash ~/.claude/skills/vt-c-project-register/scripts/check_registration.sh

Act on the emitted status line (stdout); any line other than UNREGISTERED … means continue silently (keeps the gate soft even if the vocabulary grows): - REGISTERED, TOOLKIT_REPO, NOT_GIT, or DEGRADED … → continue silently. - UNREGISTERED skips=N escalate=<bool> → offer registration (soft gate — never block): - Ask (AskUserQuestion): "This project isn't registered in the toolkit, so its learnings won't reach the intake pipeline. Register now?" - If escalate=true, strengthen the wording: note that learnings have not been reaching the toolkit across N sessions. - Register now → invoke /vt-c-project-register. - Skip for now → run bash ~/.claude/skills/vt-c-project-register/scripts/check_registration.sh --record-skip, then continue.

Step 1: Parse Argument

Read the argument passed to /vt-c-quickfix. This becomes the initial title for the audit entry and the git commit message.

If no argument was provided, ask for a description in Step 2.

Step 2: Collect Context

Use AskUserQuestion to gather: - description — one-line description of what to fix (pre-filled from argument if provided) - trigger — what prompted this fix (e.g., "PM noticed typo during demo", "spotted in QA review") - reason — short human-readable rationale (e.g., "Dashboard heading misspelled") - domain — optional product area tag (e.g., "VisiMatch", "visitrans.de"; blank = omit) - affected files — optional list of files to edit (blank = Claude identifies candidates from description)

Step 3: Route Decision

Use AskUserQuestion with two options:

  • "Fix now" → continue to Steps 4–9
  • "Create a Spec instead" → invoke /vt-c-spec-from-requirements and exit

If the user selects "Create a Spec", hand off to /vt-c-spec-from-requirements with the description collected in Step 2. EXIT after handoff.

Step 4: Generate Slug and Create Audit File

Derive slug from title: 1. Lowercase the title 2. Replace all non-alphanumeric characters with - 3. Collapse consecutive - to single - 4. Strip leading and trailing - 5. Truncate to 40 characters max 6. Example: "Fix typo in Dashboard Heading" → fix-typo-in-dashboard-heading

Derive filename from current date/time (local time): 

YYYY-MM-DD-HH-MM-{slug}.md
Example: 2026-05-14-22-05-fix-typo-in-dashboard-heading.md

Derive fixed_by automatically (no user prompt): 

git config user.name

If intake/quick-fixes/ does not exist, create it: 

mkdir -p intake/quick-fixes
touch intake/quick-fixes/.gitkeep

Write audit file at intake/quick-fixes/{filename}:

---
id: YYYY-MM-DD-HH-MM-{slug}
title: {title from Step 2}
date: {ISO 8601 timestamp}
trigger: {trigger from Step 2}
reason: {reason from Step 2}
domain: {domain from Step 2, or omit field if blank}
commit: ""  # see Step 8 — stays empty on no-upstream path; populated on upstream path
files: []
fixed_by: {git config user.name}
branch: fix/qf-YYYY-MM-DD-{slug}
---

<!-- Auto-generated by /vt-c-quickfix. Do not edit. -->

Security note: Sanitize the files: field values — strip any path traversal patterns (../, ~/, absolute paths). Only relative paths within the repo are valid.

Step 5: Create Quickfix Branch

git checkout -b fix/qf-YYYY-MM-DD-{slug}

If already on main or master, note: "Creating quick-fix branch from main." (advisory only, not blocking).

Step 6: Apply the Fix

Claude applies the fix directly using its edit tools.

If files were specified in Step 2: edit those files directly.

If no files were specified: identify candidate files from the description, then confirm with the user before editing.

After edits, present a diff summary and ask:

"Confirm fix? (y = proceed to commit / n = re-attempt)"

If the user rejects, re-examine the description and try again. Allow up to 3 re-attempts before suggesting escalation to a spec.

Step 7: Stage and Commit

Stage the audit file and all changed fix files: 

git add intake/quick-fixes/{filename} {...changed files...}

Commit with trailer: 

fix: {title}

Quick-Fix-Ref: intake/quick-fixes/{filename}

The Quick-Fix-Ref: trailer makes this fix discoverable via: 

git log --grep="Quick-Fix-Ref:"

Step 8: Update Audit File With File List

Patch the audit file: - files: [] → files: list of actually changed files (from git diff --name-only HEAD~1)

Leave commit: "" as-is — see Why no commit hash in the audit file below.

Amend safety check — check if branch has a remote upstream: 

git rev-parse --abbrev-ref @{u} 2>/dev/null

  • If no upstream (exit code non-zero): branch is local only → safe to amend the audit file's files: list into the fix commit: 
    git add intake/quick-fixes/{filename}
git commit --amend --no-edit
  • If upstream exists: branch was already pushed → do NOT amend (rewrites published history). Create a second commit. In this path the fix-commit hash is already final, so it can be recorded: 
    git rev-parse HEAD  # capture the fix-commit hash BEFORE adding the audit update
# then patch audit file's commit: field with that hash, plus files: list
git add intake/quick-fixes/{filename}
git commit -m "chore: record commit hash in QF audit [no-qa]"

Why no commit hash in the audit file (no-upstream path)

A commit cannot contain its own hash. After git commit --amend, the hash changes, so any hash patched in before the amend points to a dead commit. There is no fixpoint — amending again just produces another dead hash. The skill historically tried to record this hash, which never worked cleanly.

Discovery of the canonical commit instead uses the Quick-Fix-Ref: trailer that Step 7 writes into the commit message: 

git log --grep="Quick-Fix-Ref: intake/quick-fixes/{filename}"
This grep returns exactly one commit (the fix-commit, or after merge the merge-commit-of-record). No paradox.

Recovery: If amend fails for any reason, the audit file simply retains commit: "" and files: []. The user can re-run git add intake/quick-fixes/{filename} && git commit --amend --no-edit once the files list is patched in.

Step 9: Offer PR Creation

Use AskUserQuestion with three options:

Option A: "Create PR now" 

gh pr create \
  --title "fix: {title}" \
  --body "$(cat <<'PRBODY'
## Summary

Quick-fix applied via `/vt-c-quickfix`.

## Quick-Fix Audit Entries

This PR contains 1 quick fix. See full context in the audit file below.

| Date | Title | Reason | Audit File |
|------|-------|--------|------------|
| {date} | {title} | {reason} | intake/quick-fixes/{filename} |

---
🔧 Applied via [/vt-c-quickfix](plugins/core-standards/skills/quickfix/SKILL.md)
PRBODY
)"

Option B: "Push branch, I'll create PR manually" 

git push -u origin fix/qf-{date}-{slug}
Print: "Branch pushed. Create PR at your convenience."

Option C: "Leave local — I'll handle it" Print: "Reminder: run git push -u origin fix/qf-{date}-{slug} when ready."

Edge Cases

Slug collision (two fixes in the same minute): append -2, -3 etc. to the filename if it already exists.

On main/master branch: warn "You're on main. A quickfix branch will be created from main." — advisory only, not blocking.

Audit file accumulation: all files in intake/quick-fixes/ are permanent. No cut/archive mechanism — files are small and git history is the ledger.

Escalation: if the fix turns out to be more complex than expected at any step, offer to hand off to /vt-c-spec-from-requirements with the already-collected context.

Success Criteria

  • intake/quick-fixes/{filename}.md exists with all required frontmatter fields
  • files: field is populated (not []) after Step 8
  • commit: field is populated only on the upstream-exists path (no-upstream path leaves it empty — see Step 8 "Why no commit hash")
  • Quick-Fix-Ref: trailer present in the commit message — this is the canonical discovery path, independent of the commit: field
  • fix/qf- branch exists with the fix committed
  • PR body (if created) contains ## Quick-Fix Audit Entries section