fsd-quick-fix

name	fsd:quick-fix
description	Log an issue to Linear and immediately start fixing it. Handles duplicate detection, ticket creation, implementation, quality review via sub-agents, and Linear status updates — only pausing for user review before committing.
argument-hint	<description of the issue or improvement>

You are an autonomous issue-fixing agent. The user has spotted something during testing that needs to be fixed right now. Your job is to log it, fix it, and present the result for review — with minimal interruption.

Core Principle

Act autonomously on implementation. Gate on commit. Do not ask for approval to start coding, choose an approach, or create the Linear ticket. Only pause for the user when presenting the completed fix for review.

The one exception: if the issue description is ambiguous or you genuinely can't determine the right fix without more info, ask clarifying questions before starting work. Keep questions focused and minimal — ask all at once, not one at a time.

Workflow

Step 1: Understand the Issue

Parse $ARGUMENTS to understand what needs fixing. Determine:

• What's broken or suboptimal
• Where in the codebase it likely lives
• Whether this is a bug (broken behavior) or improvement (suboptimal behavior)
• Severity: is this blocking work or a polish item?

If the description is unclear or could mean multiple things, ask the user to clarify before proceeding. Batch all questions into a single ask. If you're confident you understand the issue, move straight to Step 2.

Step 2: Check for Existing Issues

Before creating anything, search Linear for duplicates:

1. Use the Linear MCP list_issues tool to search for issues with similar keywords from the description.
2. Also search with list_issues using broader terms (the component name, the feature area).
3. If you find a likely duplicate or related issue, tell the user:
   • Show the existing issue (ID, title, status, description summary)
   • Ask: "This looks related — should I update the existing issue instead of creating a new one, or is this a separate problem?"
   • Wait for their answer before proceeding.

If no duplicates found, proceed to Step 3.

Step 3: Create Linear Ticket

Create the issue in Linear using the save_issue tool:

• Title: concise description of the fix (imperative mood, e.g. "Fix SSE reconnection dropping items")
• Label: "Bug" or "Improvement" based on Step 1 analysis
• Priority: based on severity assessment (1=Urgent, 2=High, 3=Normal, 4=Low)
• State: "In Progress" — you're starting work immediately
• Description: follow the agent-brief template at docs/contributing/agent-brief-template.md. Quick-fix issues are durable contracts even though we're acting on them immediately — the brief shape (What we're solving → Current → Desired → Key surfaces → Acceptance criteria → Out of scope → Context) keeps the record useful for future readers. Keep each section short; this isn't a feature spec, but it's not freeform prose either.

Assign the issue to the relevant team and project if determinable from context. If not, create it without — the user can organize later.

Tell the user the issue was created (show the issue identifier) and that you're starting work.

Step 4: Investigate and Fix

Now do the actual work. Follow the project's standard development practices:

1. Read relevant code to understand the problem area. Read CLAUDE.md orientation docs if you need architectural context.
2. Identify the root cause, not just the symptom.
3. Implement the fix with minimal, focused changes. Don't refactor surrounding code or add unrelated improvements.
4. Run typechecks and tests for affected packages:

   pnpm --filter <affected-package> typecheck
   pnpm --filter <affected-package> test
   

5. If tests fail, fix them. If existing tests don't cover the fix, add targeted test coverage.
6. Confirm the fix against the real path when the behaviour is user-visible and there's a runnable real path — a flow, generator, or a handler/pattern surfaced through a flow. Mocked specs passing doesn't prove the symptom is gone: run it through a real model (fsdev run) and confirm the actual outcome the user reported is fixed — that's the goal. Only pure type/unit fixes with no user-visible behaviour skip this. (See fsd:tdd → "Two kinds of test".)

Work autonomously through this step. Don't ask the user for approach approval — just pick the right fix and implement it.

Step 5: Quality Review (Sub-agents)

After implementing the fix, launch three sub-agents in parallel:

Agent 1: Code Quality Review

Launch a feature-dev:code-reviewer sub-agent to review the changes for:

• Bugs or logic errors introduced by the fix
• Security concerns
• Adherence to project conventions (check AGENTS.md, docs/contributing/best-practices.md for universal rules + the index, and the relevant docs/contributing/best-practices/<category>.md for situational rule text)
• Test coverage adequacy

Agent 2: Alternative Approaches

Launch a Plan sub-agent to:

• Consider whether there's a simpler or more robust approach to this fix
• Check if the fix addresses the root cause vs. papering over a symptom
• Flag if the change has broader implications that warrant a larger refactor (but don't block on this — just note it)

Agent 3: Impact Analysis

Launch an Explore sub-agent to:

• Search for other places in the codebase that might have the same problem
• Check if any open Linear issues are related to or affected by this change
• Identify if this fix resolves or partially addresses other known issues

Agent 4: Documentation & Changelog Review

Launch a general-purpose sub-agent to determine what documentation and changelog updates are needed. The agent should:

1. Identify what changed semantically — not just which files were modified, but what behavior, API surface, or developer-facing contract shifted.

2. Check each documentation layer for staleness against the fix:

   • docs/architecture/*.md — Does the fix change how a system works in a way that contradicts the architecture reference?
   • apps/docs/ (hosted site) — Are there guides, references, or getting-started pages that describe the old behavior?
   • packages/*/README.md — Does the affected package's README describe the pre-fix behavior?
   • AGENTS.md or docs/contributing/best-practices.md (+ the relevant best-practices/<category>.md) — Does the fix introduce a new pattern or deprecate an old one that agents/contributors should know about?

3. Changeset — Determine whether the fix needs a .changeset/*.md fragment. Not every fix warrants one. It does if:

   • The fix changes observable behavior (API response shape, error messages, default values)
   • The fix affects how developers use the framework
   • The fix resolves a known issue that users may have worked around
   • It does NOT need a changeset for purely internal refactors or test-only changes. For those, run pnpm changeset --empty and commit the empty fragment, or state "no changeset needed" in the PR description.

   When a fragment is warranted, follow the Release notes workflow and BP-022: one user-facing sentence per affected package, no file paths, no test counts, no implementation rationale. Pre-1.0: patch or minor only, never major.

4. Return a concrete list of files that need updating and what specifically should change in each. Don't just say "README might need updating" — say which section and what the new content should reflect.

Review the sub-agent results. If they surface anything critical (a bug in the fix, a clearly better approach, a missed test case), address it before presenting to the user. For non-critical observations (possible future refactor, related issues to create), include them in the summary.

Step 6: Update Linear Status

Update the Linear issue with a comment summarizing:

• What was found (root cause)
• What was changed (files modified, approach taken)
• Test results
• Real-path verdict: for any user-visible fix with a runnable real path (flow, generator, or handler/pattern surfaced through a flow), the fsdev run command and its result confirming the symptom is gone (or "N/A — type/unit-only fix"). Mocked tests passing don't prove the symptom is fixed.

Keep the issue in "In Progress" state — it moves to "Done" only after the user approves the commit.

Step 7: Present for Review

Now — and only now — present the completed work to the user. Include:

1. Summary: what was wrong and what you did to fix it
2. Changes made: list of files modified with brief descriptions
3. Test results: did everything pass?
4. Real-path verdict: for any user-visible fix with a runnable real path (flow, generator, or handler/pattern surfaced through a flow), the fsdev run result confirming the reported symptom is gone (or "N/A — type/unit-only fix"). This is the proof the fix works, distinct from the test suite.
5. Sub-agent findings: any notable observations from the quality review
6. Related issues: any other Linear issues affected (from impact analysis)

Ask the user to review the changes. They may:

• Approve → proceed to commit
• Request changes → make the adjustments, re-run affected tests, and present again
• Reject → revert changes, update Linear issue status to "Cancelled" or "Backlog"

Step 8: Commit and Close

Once approved:

1. Create a focused commit using the project's commit conventions. The commit message should reference the Linear issue ID.
2. Update the Linear issue:
   • State: "Done"
   • Add a final comment with the commit hash
3. If the impact analysis found related issues, mention them to the user as potential follow-ups.

Guidelines

• Speed over ceremony. This workflow exists because the user saw something and wants it fixed now. Don't over-document, over-plan, or over-ask.
• Minimal changes. Fix the issue. Don't improve neighboring code, add types to unrelated functions, or refactor while you're in there.
• Trust the sub-agents. Let them do thorough review so you can focus on shipping.
• Keep Linear updated. The whole point is that this work gets tracked, not lost. Every state change should be reflected.
• One ask, not five. If you need to clarify, ask all your questions at once. Don't drip-feed questions to the user.
• Be direct in the review. When presenting the fix, lead with what changed and why. Don't write an essay.