docs(solutions): record why skill gates state conditions, not git commands

[tmchow]

Summary

A learning captured from #1385, where one decision gate in ce-debug — "does this verified fix go out as a PR?" — was rewritten six times across nine reviewed heads, and every revision was wrong for some ordinary git configuration.

The part worth keeping: not one reviewer ever said the gate's intent was unclear. Every finding was a prescribed git command failing in a configuration nobody had enumerated — a branch with no upstream, a local branch ahead of its remote, a branch that already had an open PR. The explanation was never the defect; the mechanism was. The fix was to delete the commands and state the condition, leaving the agent to establish it against the repo actually in front of it.

Why this is not already covered

git-workflow-skills-need-explicit-state-machines.md was cited against that simplification twice during review, so the fair question is whether this duplicates it. It does not — the two are close to inverses:

	state-machine doc	this doc
Cause	too few explicit observations — state carried past a transition that invalidated it	too much prescription — a mechanism specified where a condition sufficed
Remedy	add re-checks at the decision point	delete the commands, name the condition
Applies to	skills that execute git transitions	skills that delegate them

Folding them together would have put two opposed causes under one root cause. The boundary neither doc previously stated: prescribe a mechanism when the skill owns that mechanism; state a condition when another skill owns it.

The sharpest evidence is that the state-machine doc's own §3 prescribes @{u} and git log <upstream>..HEAD — two of the exact commands that broke in ce-debug. They are correct there, because ce-commit-push-pr executes the transitions and handles the no-upstream case. Copied into a skill that only decides whether to hand off, they broke.

Follow-up this surfaces

That doc reads broader than its evidence and wants a scope caveat: its title and prevention lines say "Git/GitHub skills" with no ownership qualifier, and it carries no applies_when block, so its ce-commit / ce-commit-push-pr scope never reaches a reader who arrives by grep. Two independent reviewers reading it as a general mandate is the demonstration, not a hypothetical. Deliberately not done here — cross-doc edits belong to ce-compound-refresh.

Vocabulary

Four terms the gate turns on, each verified against how they are actually used in the tree: offered work (in an open PR, as against merely pushed or merely present), fix-owned files, issue of record, residual.

Validation

Grounding validation ran as an independent pass: 15 claims checked against the tree, 12 verified with quoted file:line evidence — and it caught two count errors in the author's own account of events. The draft said five of six revisions were wrong when the enumeration shows all six, and "ten review rounds" when the PR record shows nine reviewed heads. Both are corrected to what the record substantiates.

bun test 3101 pass / 0 fail; release:validate clean.

Related: #1385

Security Disclosure

No security-relevant changes — documentation only. The doc describes a shell-injection finding from #1385 as supporting evidence; nothing here changes executable behavior.

Agent Disclosure

• Model: Claude Code · claude-opus-5[1m]

[cursor]

PR Summary

^{Cursor Bugbot is generating a summary for commit c3afe97. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c3afe97ae2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Scope residual to the workflow that uses this meaning

Because this glossary defines shared repository vocabulary, this definition conflicts with established uses of “residual”: skills/ce-doc-review/references/review-output-template.md:85-87 defines residual concerns as unconfirmed, non-actionable observations rather than accepted/deferred findings, and skills/ce-debug/references/post-fix-handoff.md:19 permits a committed residual-findings file when neither a PR nor tracker is available. Future authors following this entry would therefore misclassify review output and omit a supported durable sink; qualify it as the ce-debug handoff meaning or reconcile it with the existing contracts.

AGENTS.md reference: AGENTS.md:L73-L73

Useful? React with 👍 / 👎.