Do Issue Guided

---
name: do-issue-guided
description: Work on a GitHub issue interactively with the user. Proceeds autonomously through routine work but pauses for confirmation at key decision points and when uncertain.
argument-hint: issue number (e.g., 123)
user-invocable: true
disable-model-invocation: false
---

**Depends on:** mav-scope-boundaries, mav-git-workflow, mav-github-issue-workflow, mav-create-solution-design, mav-create-tasks, mav-plan-execution, mav-local-verification, mav-bp-cicd, mav-claude-code-recovery, mav-bp-logging, mav-bp-alerting, mav-systematic-debugging, do-docs, do-cybersecurity-review, do-pullrequest-review

# Work on GitHub Issue (Guided)

Work on GitHub issue `` interactively. Follow every phase in order. Do not skip phases. Proceed autonomously through routine work, but pause for user confirmation at key decision points marked with **🔲 Checkpoint**.

## Preflight (mandatory)

Run this **first**. If it exits non-zero, halt and report the stderr output to the user verbatim. Do not proceed.

```bash
uv run maverick preflight do-issue-guided
```

The check verifies the project is initialised and required tools (`gh`, `git`, `uv`) are on PATH. PR code review runs locally as the `agent-code-reviewer` subagent (see Phase 6); the optional CI-side re-run described in `mav-bp-remote-code-review` is not required.

## Before You Begin

If `` is empty or not a valid issue number, ask the user for the issue number before proceeding. Do not attempt any phase without it.

## Phase 1-2: Understand the Issue and Solution Design (subagent)

Run Phases 1 and 2 as a subagent to keep the main context window clean for implementation.

1. Initialise the issue state file per the mav-github-issue-workflow skill.
2. Dispatch the **agent-issue-analyst** agent with:
   - Issue number: ``
   - Mode: `guided`
3. When the agent returns, verify:
   - `.claude/issue-state.json` has `phase` set to `design`
   - `.claude/issue-state.json` has `comments.design` set to a comment ID
4. If the agent flagged ambiguities, present them to the user and wait for answers before continuing.

**🔲 Checkpoint — Design review:** Present a brief summary of the solution design to the user. Include the key approach, main components affected, and any trade-offs. Ask the user to confirm or suggest changes before proceeding. Do not continue until the user approves.

## Phase 3: Create Tasks (subagent)

Run Phase 3 as a subagent to keep the main context window clean for implementation.

1. Dispatch the **agent-github-issue-planner** agent with:
   - Issue number: ``
   - Design comment ID from `.claude/issue-state.json`
2. When the agent returns, verify:
   - `.claude/issue-state.json` has `phase` set to `tasks`
   - If < 5 tasks: `.claude/issue-state.json` has `comments.tasks` set to a comment ID
   - If >= 5 tasks: `.claude/issue-state.json` has `has_sub_issues` set to `true`
3. If the agent flagged scope concerns, present them to the user.

**🔲 Checkpoint — Tasks review:** Present the task list to the user — each task title and description, their order, and any dependencies. Ask the user to confirm, reorder, add, or remove tasks. Do not continue until the user approves.

## Phase 4: Create Branch

1. Derive the branch name per the mav-github-issue-workflow skill (branching conventions).
2. Resolve the base branch from config:
   ```bash
   STORY_BASE=$(uv run maverick git-workflow story-base)
   ```
   Create the branch from `$STORY_BASE`.
3. Update phase to `branch` in the state file.

## Phase 5: Execute Tasks

1. Check for project-level skills in `docs/maverick/skills/`. For each topic directory that contains a `SKILL.md`, read it. These project skills provide codebase-specific guidance (libraries, patterns, configuration) that supplements the best-practice skills. If none exist, continue without them.
2. Update phase to `implement` in the state file.

**If `.claude/issue-state.json` has `has_sub_issues: true`:**

1. Read the tasks summary comment on the parent issue for the execution order
2. For each sub-issue in execution order:
   1. Read the sub-issue description
   2. Implement the change described
   3. Run verification (lint, typecheck, tests) per the mav-local-verification skill
   4. Commit with a conventional commit referencing the parent issue
   5. Update the tasks summary comment: mark the sub-issue as complete
   6. Close the sub-issue
3. After all sub-issues are complete, run the full verification suite

**Otherwise (checklist tasks):**

1. Read the tasks comment on the issue
2. For each task in order:
   1. Implement the change described
   2. Run verification (lint, typecheck, tests) per the mav-local-verification skill
   3. Commit with a conventional commit referencing the issue number
   4. Update the tasks comment: check off the completed task (`- [ ]` to `- [x]`)
3. After all tasks are complete, run the full verification suite

Follow the mav-plan-execution skill for the execution loop, verification discipline, failure handling, and crash recovery. In guided mode, it will:
- Provide brief progress checkpoints every 3-4 tasks.
- Pause and ask the user when uncertain about an implementation approach.
- Pause and discuss with the user when a design assumption proves wrong.
- Ask the user for help immediately when a task fails after 2 fix attempts.

## Phase 6: Code Review

1. Dispatch the agent-code-reviewer agent with the issue requirements and the diff (`git diff $(uv run maverick git-workflow story-base)...HEAD`).
2. The reviewer performs two-stage review: spec compliance first, then code quality.
3. If spec compliance fails, stop — fix the gaps before requesting re-review.
4. Process code quality feedback per the do-pullrequest-review skill:
   - Read all items before acting.
   - Clarify unclear items before implementing any.
   - Verify each suggestion against the codebase.
   - Push back with reasoning when a suggestion is incorrect.
   - Implement valid fixes one at a time, verifying after each.
5. If fixes changed the implementation approach, update the tasks comment on the issue.
6. Request re-review if there were critical or spec compliance issues. Repeat until approved.
7. Update phase to `review` in the state file.

**🔲 Checkpoint — Review results:** Present a summary of the review outcome to the user — what was flagged, what was fixed, and what was pushed back on. If there were significant changes during review, highlight them.

## Phase 7: Documentation Review (mandatory)

This phase **always runs** before push. The agent decides whether any
docs work is needed; the workflow does not skip the analysis based on
its own heuristic.

The agent is dispatched with a **pre-filtered shortlist** of docs the
diff plausibly touches, not the open-ended "audit every doc" brief.
On prior issues the unbounded brief ate ~6 min of wall clock on a
15-file diff. The agent still reports any out-of-shortlist docs it
believes are impacted; those surface as a follow-up note for you to
review.

1. Compute the diff and changed paths:

   ```bash
   BASE=$(uv run maverick git-workflow story-base)
   git diff "origin/${BASE}...HEAD" > /tmp/diff.patch
   git diff --name-only "origin/${BASE}...HEAD" > /tmp/changed-paths.txt
   ```

2. **Build the candidate doc shortlist.** Derive search terms from the
   diff (basenames + top-level directories from changed paths, plus
   identifier-like tokens introduced or removed in added/removed lines).
   Grep every `docs/` tree in the repo. An empty shortlist is valid.

   ```bash
   {
     cut -d/ -f1 /tmp/changed-paths.txt
     sed 's|.*/||; s|\.[^.]*$||' /tmp/changed-paths.txt
     grep -E '^[+-][^+-]' /tmp/diff.patch \
       | grep -Eo '\b(function|def|class|interface|type|const|export)[[:space:]]+[A-Za-z_][A-Za-z0-9_]+' \
       | awk '{print $NF}'
   } | awk 'length($0) >= 3' | sort -u > /tmp/doc-terms.txt

   mapfile -t DOC_ROOTS < <(find . -type d -name docs \
     -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.venv/*')

   : > /tmp/doc-shortlist.txt
   if [[ ${#DOC_ROOTS[@]} -gt 0 && -s /tmp/doc-terms.txt ]]; then
     while IFS= read -r term; do
       grep -rlF -- "$term" "${DOC_ROOTS[@]}" 2>/dev/null || true
     done < /tmp/doc-terms.txt \
       | grep -E '\.(md|mdx)$' \
       | sort -u > /tmp/doc-shortlist.txt
   fi
   ```

3. Dispatch the **agent-tech-docs-writer** agent with:
   - **Mode:** `update` (per `do-docs`)
   - **Diff:** `/tmp/diff.patch`
   - **Candidate docs:** the contents of `/tmp/doc-shortlist.txt`. If
     the file is empty, pass the literal string
     `<empty — scan only for gaps requiring new coverage>`.
   - **Instructions:**
     - Read each candidate doc. Update only sections rendered stale by
       the diff; do **not** refactor unrelated content.
     - If the diff introduces a component, subsystem, or architectural
       change with no coverage anywhere in `docs/`, create the new
       document.
     - If you find a doc **outside the candidate list** that you
       believe is impacted, **list its path in your return payload —
       do not edit it.** One-pass dispatch: no widen-and-retry; the
       caller surfaces these as a follow-up note for the user.
     - Returning "no doc changes required" is a valid outcome and must
       be reported explicitly.
4. **Checkpoint — Review docs outcome with the user:** show what was
   updated or created (or the explicit no-op decision), surface any
   out-of-shortlist docs the agent flagged, and confirm before pushing.
   If updates are inaccurate or out of scope, push back and ask the
   agent to revise.
5. Commit any doc changes with a `docs:` conventional commit.

## Phase 8: Pre-push Cybersecurity Review (mandatory)

This phase **always runs** before push. Any changed code AND any code that could be impacted by the changes (callers, importers, dependents) must be reviewed by `do-cybersecurity-review` before the push proceeds.

1. Compute the full diff: `git diff $(uv run maverick git-workflow story-base)...HEAD`.
2. Dispatch the **do-cybersecurity-review** skill with:
   - **Mode:** `update`
   - **Diff:** the output of step 1, passed via stdin or as a file path
   - **Instructions:** review the changed code AND the impact set (callers, importers, dependents — bounded to one or two hops). Return the structured outcome (verdict + findings).
3. **Checkpoint — Review security outcome with the user:** show the verdict and any findings. If BLOCKING, halt and route the user back to Phase 5 (implement) to resolve the issues before re-running this phase. If FINDINGS or PASS, confirm with the user before proceeding to push.
4. If FINDINGS, fold the security findings into the PR description draft so they are visible to the human reviewer in Phase 9.

## Phase 9: Push and Verify CI

1. Run pre-push verification per the mav-local-verification skill (lint, typecheck, tests). Fix any failures before pushing.
2. Push the branch to remote.
3. Monitor CI status per the mav-bp-cicd skill. If CI fails, read the failure logs, fix locally, and push again. Do not proceed until CI passes.

## Phase 10: Update Issue and Create PR

1. Post a completion comment on the issue per the mav-github-issue-workflow skill (post completion comment pattern).
2. Create a pull request per the mav-github-issue-workflow skill (PR pattern).
3. Update phase to `complete` in the state file.
4. Clean up the state file.

**🔲 Checkpoint — Done:** Present the PR URL to the user and summarise what was delivered.

## Rules

- **Pause at checkpoints** — every phase marked with 🔲 requires user confirmation before continuing.
- **Work autonomously between checkpoints** — do not ask for permission on routine implementation work. Only ask when uncertain, blocked, or at a checkpoint.
- **Run verification** after each task and after all tasks. Do not declare success if checks fail.
- **Never commit directly** to the story base branch.
- **Use conventional commits** that reference the issue number (e.g., `feat: add rubric export (#42)`).
- **Always create a PR** at the end — deliver a complete result.

<!-- maverick-plugin-version: 3.3.5 -->