work-issue

name	work-issue
description	Work a tracker issue from its orgmap workspace — detect the stage (planning vs executing), say what you'll do, then act only on approval. Use when the user invokes `/work-issue <id>`, or asks to "work", "plan", "start", or "continue" a ticket / work item / issue by number. Argument is the work-item id.

work-issue

You are working work item <id> (the argument; if it has a leading #, ignore it).

Follow the steps below. Before you change anything, tell the user what you're going to do and wait for approval — see the rule at the end.

0 · Locate the workspace root

Issue workspaces live in the orgmap issues directory, resolved in this order:

1. $ORGMAP_ISSUES_DIR if set.
2. <orgmap-repo>/issues/ otherwise — the default tracker/fetch_issue.py writes to.

If you can't determine it, ask rather than guessing. Call it ISSUES_ROOT.

1 · Open the issue workspace

Glob ISSUES_ROOT/<id>-* to find this issue's folder, named <id>-<slug>.

• If nothing matches, STOP: tell the user the workspace doesn't exist yet and that it needs python3 <orgmap-repo>/tracker/fetch_issue.py <id> first. Offer to run it, then stop.
• Otherwise, call that folder ISSUE_DIR.

2 · Load the context

Read both — they are the source of truth for this issue:

• ISSUE_DIR/work-item.md — the tracker item (title, description, acceptance criteria, repro steps, comments, images).
• ISSUE_DIR/plan.md — the plan and the workflow stage.

3 · Find the current stage

In plan.md, read the line **Stage:** <stage> — one of planning, executing, review, done.

If that line is missing (older workspace), infer it: if the Approach / Tasks sections are still the empty placeholders it's planning, otherwise executing — then add the **Stage:** line to plan.md.

4 · Act according to the stage

Stage = planning — produce an agreed plan; do NOT write code yet

1. Study work-item.md and the current repo. You are running inside the target code repo — work in the current directory. Use read-only tools (Read, Grep, Glob, git status/log/diff) to find where the change belongs.
2. Draft a concrete plan: the problem restated, the approach, the specific files/areas to touch, risks and open questions, and an ordered task list.
3. Show it to the user and ask for edits/approval.
4. Once approved, write it into the Approach, Tasks, and Open questions sections of ISSUE_DIR/plan.md, set **Stage:** executing, and ask whether to start executing now.

Stage = executing — implement the agreed plan

1. Re-read the Approach and Tasks in plan.md to see what's done and what's next.
2. Tell the user the next task and exactly what you'll change — then wait for the go-ahead.
3. On approval, implement that single increment in the current repo, scoped to the task. Run the project's build/tests if they exist and report the result.
4. Update plan.md: tick off finished tasks and add a short note under Notes & decisions. When every task is done, set **Stage:** review.

Stage = review or done

Summarise what's been done (from plan.md plus git diff / git log) and ask what the user wants next — final checks, open a PR, or close it out.

Proving the work

When a change is visual or user-facing, a green test suite is weak evidence. The feature-demo skill drives the running app with Playwright and produces a captioned video plus a PDF of annotated screenshots, with on-screen assertions for measurable acceptance criteria. Offer it once a task is implemented and the app runs locally — it routinely catches render and template bugs that passing tests miss.

Opening a PR

Once the branch is pushed:

python3 <orgmap-repo>/tracker/create_pr.py <id> --repo "<Repo Name>" --source <branch> [--target <branch>]

It opens the PR, writes a short description, and links the work item. Re-running for the same branch reuses the existing open PR rather than erroring. This needs a token with Code (Read & Write) and Work Items (Read & Write) — wider than the read-only token fetch_issue.py needs.

Opening a PR is publishing work to a shared place. Confirm with the user before running it, every time.

Rule — propose before acting

Every run, start with a short note (≤6 lines): the issue title, the detected stage, and exactly what you intend to do this run. Then STOP and wait for confirmation. Never edit code or files before approval.

plan.md is the single source of truth for stage and progress. Code changes go in the current working directory — never inside the orgmap repo or the issue workspace.