Enhance start-work skill to handle doc-only decision stories
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 1
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 7
Description
Goal
Extend the start-work skill so that when a user invokes it on a story whose entire
deliverable is a documented decision in the work item — and supplies the conclusion in
the same invocation — the skill skips branch/worktree creation and goes straight to
assign + document + close.
Context
Phase 2 / decision-only stories (e.g., the E41 Bigvars migration audit and policy
stories) produce written conclusions, not code. Spinning up a worktree, marking Active,
running codebase research, and emitting a draft plan adds friction with no payoff when
the user has already made the call.
Demonstrated repeatedly during the E41 Bigvars migration session (ADO #7269, #7271):
- User invoked
/start-work 7269. This is a non issue, personid == customerid. all we need to do is assign, document and close the user story. - Same pattern for #7271 ("non-issue, single site, always GTL(2)").
Today the skill's instructions say "Worktree is the default. Only fall back to in-place
branch creation when --no-worktree is explicit." But a doc-only story doesn't need
either path.
Proposed behavior
After Step 1 (fetch the card) and before Step 3 (locate the script):
-
Detect a doc-only signal when ALL of the following hold:
- The card's AC is documentation-only (heuristics: AC items mention "decision",
"paragraph", "documented", "recorded", "in the PR description", "on the work
item"; no AC item mentions code, file paths, tests, or a PR target). - The user's
/start-workinvocation contains the conclusion (heuristics:
"this is a non-issue", "all we need to do is", "decision is", "verified that",
"no-op"). - Effort is small (≤ 0.5 days, no code-deliverable parent).
- The card's AC is documentation-only (heuristics: AC items mention "decision",
-
If the signal fires, confirm with the user before bypassing the heavy flow:
"Story #X looks like a doc-only decision and you've supplied the conclusion.
I'll skip the worktree and just update the description + assign + close.
Confirm to proceed." -
On confirm, in one
wit_update_work_itemcall (orgh issue closewith comment
for GitHub):- Tick the AC checkboxes inline.
- Append a "Decision" section with the user's conclusion + cross-reference.
- Set
System.AssignedToto the current user. - Transition
System.Statedirectly toClosed.
Why a skill enhancement over static documentation
This is behavioral logic, not documentation. The user's intent ("trivial, just close
it") is signaled in the invocation and should bypass the heavier flow automatically.
Documenting the pattern in CLAUDE.md alone leaves Claude doing the heavy lift each
time and waiting for explicit user redirection.
Acceptance criteria
- New conditional path in
start-work.sh(or the skill prompt) for the doc-only +
stated-conclusion case. - User confirmation prompt before bypassing worktree creation.
- Single
wit_update_work_itemcall ticks AC, appends Decision, assigns, closes. - GitHub equivalent (no state transition;
gh issue closewith a comment containing
the decision).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading start-work.sh or the skill prompt around the fetch-card and script-location steps, then trace the existing wit_update_work_item and gh issue close entry points. Add the confirmed doc-only path for both work-item and GitHub flows, including AC updates, the decision text, assignment, and closure, and verify each acceptance criterion.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github, shell
- Domain
- cli, devtools, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 62/100