Quickfix Gnadd

Quickfix

Land one small change on main through a PR in a single flow. No issue is created — the PR title and body are the permanent record. This is a fast path through the safety rails (branch, PR, CI gate, squash merge), never a bypass around them.

Auto-Invocation Gate

If this skill was auto-selected from context rather than explicitly invoked with /quickfix-gnadd, stop before running git or GitHub commands. Briefly explain why a quickfix appears to fit and ask: "Run /quickfix-gnadd now?" Proceed only after confirmation.

GNADD Invariants

• Nothing lands on main without a PR — quickfix included.
• The deterministic guard is the contract: small diffs only, and never the safety machinery (bin/, scripts/, .github/, any gnadd.sh copy). A guard refusal is a redirect to the full loop, not an obstacle to work around.
• One quickfix = one concern. Batching unrelated fixes is out of scope; each gets its own invocation.
• The merge is CI-gated in the script itself: quickfix merge refuses unless the named check passed.
• For broader workflow guidance, use help-gnadd.

Mechanics

All git mechanics run through the bundled script — gnadd.sh in this skill's directory. When it exits with state=<NAME>, that is a human decision point — have the conversation, never work around it with raw git. If the script is missing, stop and tell the user to reinstall the GNADD skills per help-gnadd's Install & Update guidance (npx skills update -y in the scope used at install, or scripts/sync.sh for local-checkout installs).

The Stated Gates (tell the user up front)

This flow has exactly two human gates; everything between them runs without further prompting:

1. PR approval — the drafted title/body shown before creation. Approving it also authorizes the merge once CI passes; say so when presenting it.
2. Any state= halt — guard refusals, CI failures, conflicts. These stop the flow and get discussed.

1. Scope Check (judgment, before any command)

A quickfix is one trivial, self-contained change: a typo, a doc line, a small config value. If what the user describes has real behavioral surface, needs a spec, or bundles several concerns, say so and route to /new-issue-gnadd — before touching git. The deterministic guard in step 3 backstops this judgment; it does not replace it.

2. Survey And Branch

bash "<skill-dir>/gnadd.sh" state

Derive <slug> from the change: short kebab-case (e.g. readme-typo).

• Clean tree: create the branch, then make the described change on it:

  bash "<skill-dir>/gnadd.sh" quickfix start <slug>
  

• Dirty tree on main (the change was already made before invoking): confirm with the user, then carry it losslessly:

  bash "<skill-dir>/gnadd.sh" quickfix start <slug> --carry
  

• Already on a quickfix/<slug> branch (a doctor --rescue-main quickfix/<slug> rescue leaves you there): skip branch creation. The commits it holds are the change; go to step 3.

• Dirty tree elsewhere, or any state= halt (DIVERGED_MAIN, QF_BRANCH_EXISTS, FF_REFUSED): stop and resolve with the user; gnadd.sh doctor is the recovery path for bad states.

3. Verify, Commit, Ship

Make the change if it isn't already in the tree, then run the project's tests:

bash "<skill-dir>/gnadd.sh" test

A failing suite stops the flow — a quickfix must not ship on red. Commit with a conventional message (no issue reference; there is no issue):

bash "<skill-dir>/gnadd.sh" guard-commit
git add <files>
git commit -m "<type>: <summary>"

Then ship — this runs the deterministic guard and pushes:

bash "<skill-dir>/gnadd.sh" quickfix ship

• state=TOO_BIG or state=PROTECTED_PATH: the change does not qualify. Tell the user exactly why, and route to the full loop: /new-issue-gnadd, then /start-issue-gnadd — the work is safe on the current branch and can be carried into that conversation.
• pr_exists=true: an open PR already exists for this branch — resume at step 5 with that PR number.

4. Draft And Create The PR

Show the draft for approval before creating. Title: the commit summary. Body: what changed and why, in a few lines — this is the permanent record, so say why the change was worth making, not just what it touches. Remind the user that approval authorizes the merge once CI passes.

gh pr create --title "<title>" --body "$(cat <<'EOF'
<what and why>

Quickfix: no issue; this PR is the record. Guard-verified small diff;
merges automatically once CI passes.
EOF
)"

If the guard passed only because of an override, the footer must say so instead of "Guard-verified small diff": name the variable and the value (for example "Guard passed with GNADD_QF_MAX_LINES=50"). A footer that claims a verified small diff after an override is a false record.

Capture the PR number from the output URL.

5. CI-Gated Merge

Wait for checks, then merge — the script re-verifies the check at merge time:

gh pr checks <PR> --watch
bash "<skill-dir>/gnadd.sh" quickfix merge <PR>

The default gate is the check named test (override: --check <name>, or GNADD_QF_CHECK). The guard's budget has its own overrides, GNADD_QF_MAX_FILES (default 3) and GNADD_QF_MAX_LINES (default 30), set in the environment of the quickfix guard call. Use one only on the user's explicit say-so, and state it in the PR footer (step 4). A newly added VISION.md is exempt from the line budget without any override. Handle halts:

• state=QF_CHECKS_PENDING: still running; wait and re-run.
• state=QF_CHECK_FAILED: stop and discuss — never wave past a red CI.
• state=QF_NO_CHECKS / state=QF_CHECK_NOT_FOUND: nothing automated (or nothing recognizable) verified this PR. Surface that to the user; only with their explicit go-ahead re-run with --no-check or --check <name>.
• state=PR_CONFLICTING: hand resolution to the human, as always.

6. Sync And Clean Up

bash "<skill-dir>/gnadd.sh" sync-main
bash "<skill-dir>/gnadd.sh" cleanup <PR> quickfix/<slug>

The script deletes only when GitHub confirms the PR merged, the branch is that PR's head, and nothing was committed after the merged head. state=BRANCH_MISMATCH or state=UNMERGED_COMMITS means nothing was deleted: stop and report which.

Report the merge commit hash — the one-command undo (git revert <hash>).

Closing Guidance

At natural completion, report: merged PR URL, merge commit, and that main is synced and the branch cleaned up. No nudge needed — quickfix is usually invoked mid-flow of something else; hand the session back.

On a guard refusal, nudge only toward /new-issue-gnadd for the full loop.