TimZander / TimZander/claude

Enhance start-work skill to handle doc-only decision stories

Open
#135 0 comments 0 reactions 0 assignees View on GitHub

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):

  1. 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-work invocation 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).
  2. 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."

  3. On confirm, in one wit_update_work_item call (or gh issue close with comment
    for GitHub):

    • Tick the AC checkboxes inline.
    • Append a "Decision" section with the user's conclusion + cross-reference.
    • Set System.AssignedTo to the current user.
    • Transition System.State directly to Closed.

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_item call ticks AC, appends Decision, assigns, closes.
  • GitHub equivalent (no state transition; gh issue close with a comment containing
    the decision).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.