---
description: Use when asked to implement an issue end-to-end or start implementing FEAT-NNN.
argument-hint: "[type] [action] [issue-id]"
allowed-tools:
  - Bash(git:*)
  - Bash(ll-history-context:*)
arguments:
  - name: issue_type
    description: Type of issue (bug|feature|enhancement|epic). Note: epic issues are coordination containers — manage-issue surfaces them but redirects to child issues for implementation.
    required: true
  - name: action
    description: Action to perform (fix|implement|improve|verify|plan)
    required: true
  - name: issue_id
    description: Specific issue ID (e.g., BUG-004). If empty, finds highest priority.
    required: false
  - name: flags
    description: "Optional flags: --plan-only (stop after planning), --resume (continue from checkpoint), --gates (enable phase gates for manual verification), --dry-run (alias for --plan-only), --quick (skip deep research and confidence check), --force-implement (bypass confidence gate)"
    required: false
---

# Manage Issue

You are tasked with autonomously managing issues across the project. This command handles the full lifecycle: planning, implementation, verification, and completion.

## Configuration

This command uses project configuration from `.ll/ll-config.json`:
- **Issues base**: `{{config.issues.base_dir}}`
- **Categories**: `{{config.issues.categories}}`
- **Completed dir**: `{{config.issues.completed_dir}}`
- **Source dir**: `{{config.project.src_dir}}`
- **Test command**: `{{config.project.test_cmd}}`
- **Lint command**: `{{config.project.lint_cmd}}`
- **Custom verification**: `{{config.commands.custom_verification}}`
- **Status enum**: `open`, `in_progress`, `blocked`, `deferred`, `done`, `cancelled` — see `.claude/CLAUDE.md` § Issue File Format for full enum and forbidden synonyms.

### Workflow Settings
- **Phase gates**: Disabled by default (enable with `--gates` flag)
- **Deep research**: Always enabled (Phase 1.5 spawns codebase-locator, codebase-analyzer, codebase-pattern-finder)

### Directory Structure

**IMPORTANT**: The `completed/` directory is a SIBLING to category directories, NOT a child:

```
{{config.issues.base_dir}}/
├── bugs/           # Active bugs (NEVER create completed/ or deferred/ here)
├── features/       # Active features (NEVER create completed/ or deferred/ here)
├── enhancements/   # Active enhancements (NEVER create completed/ or deferred/ here)
├── epics/          # Active epics — coordination containers, NOT directly implementable
├── completed/      # ALL completed issues go here (sibling to categories)
└── deferred/       # ALL deferred/parked issues go here (sibling to categories)
```

**EPIC handling**: An EPIC is a coordination container, not a directly implementable unit. When `issue_type=epic`, do NOT proceed to implementation — instead, list the EPIC's child issues (via `parent: EPIC-NNN` references in child issues or the EPIC's `children:` frontmatter), and redirect the user to run `/ll:manage-issue` on individual children, or to run `/ll:create-sprint` with the children for grouped execution. `ll-auto` and `ll-parallel` should be invoked with `--type BUG,FEAT,ENH` to skip EPICs in batch runs.

---

## Phase 1: Find Issue

If issue_id is provided, locate that specific issue. Otherwise, find the highest priority issue of the specified type.

```bash
ISSUE_TYPE="${issue_type}"
ISSUE_ID="${issue_id}"
ISSUE_DIR="{{config.issues.base_dir}}"

# Map issue_type to directory
case "$ISSUE_TYPE" in
    bug) SEARCH_DIR="$ISSUE_DIR/bugs" ;;
    feature) SEARCH_DIR="$ISSUE_DIR/features" ;;
    enhancement) SEARCH_DIR="$ISSUE_DIR/enhancements" ;;
    epic) SEARCH_DIR="$ISSUE_DIR/epics" ;;
esac

# Find issue file
# Use strict matching: ID must be bounded by delimiters (-, _, .) to avoid
# matching BUG-1 against BUG-10 or ENH-1 against issue-enh-01-...
if [ -n "$ISSUE_ID" ]; then
    ISSUE_FILE=$(ll-issues path "${ISSUE_ID}" 2>/dev/null)
else
    # Find highest priority (P0 > P1 > P2 > ...)
    for P in P0 P1 P2 P3 P4 P5; do
        ISSUE_FILE=$(ls "$SEARCH_DIR"/$P-*.md 2>/dev/null | sort | head -1)
        if [ -n "$ISSUE_FILE" ]; then
            break
        fi
    done
fi
```

---

## Phase 1.5: Deep Research

Before creating an implementation plan, spawn parallel sub-agents to gather comprehensive context about the issue.

**Skip this phase if**: Action is `verify` (verification doesn't need deep research), or `--quick` flag is set (proceed directly to planning with issue file context only)

### Research Tasks

Spawn these agents in parallel using the Task tool:
1. **codebase-locator** - Find all related files
2. **codebase-analyzer** - Understand current implementation
3. **codebase-pattern-finder** - Find similar patterns and reusable code

Also fetch effort context: `EFFORT=$(ll-history-context --for-skill manage-issue --effort {{issue_id}} 2>/dev/null || true)`. If non-empty, include session count and cycle time in the plan preamble under "## Historical Effort".

**CRITICAL**: Wait for ALL sub-agent tasks to complete before proceeding to planning.

See [templates.md](templates.md) for detailed agent prompts and research findings template.

---

## Phase 2: Create Implementation Plan

After reading the issue and completing research, create a comprehensive plan.

**If `--plan-only` or `--dry-run` flag is set**: Stop after writing the plan (do not implement).

### Recommended: Pre-Implementation Confidence Check

Before creating the plan, consider running the `confidence-check` skill to validate implementation readiness. This is advisory (non-blocking) and uses the research findings from Phase 1.5:

```
Use Skill tool with:
  skill: "ll:confidence-check"
  args: "[ISSUE-ID]"
```

- **Score >=70**: Proceed to plan creation
- **Score <70**: Review the gaps identified and consider addressing them before planning
- **Skip if**: Action is `verify`, `--quick` flag is set, or time constraints require proceeding immediately

### No Open Questions Rule

**CRITICAL**: Before writing the plan, resolve ALL open questions:

1. **Unclear Requirements** → Ask for clarification or research further
2. **Technical Uncertainty** → Spawn additional research tasks
3. **Design Decisions** → Present options to user, get explicit approval (**only with `--gates` flag**; without `--gates`, make the best autonomous decision and document the rationale in the plan)

**The plan must be complete and actionable with no unresolved questions.**

If questions arise that cannot be resolved, mark the issue as `NOT_READY` rather than proceeding with assumptions.

### Plan Creation Steps

1. **Read the issue file** completely
2. **Incorporate research findings** from Phase 1.5
3. **Resolve any remaining questions** before proceeding
4. **Design the solution** with specific changes
5. **Write plan** to `thoughts/shared/plans/YYYY-MM-DD-[ISSUE-ID]-management.md`

### Enhanced Plan Template

See [templates.md](templates.md) for the full Enhanced Plan Template structure.

---

## Phase 2.3: Decision Gate

**Skip this phase if**: Action is `verify` or `plan`, or `--quick` flag is set.

Check the issue's `decision_needed` frontmatter field before proceeding to implementation:

```
READ decision_needed from issue YAML frontmatter

IF decision_needed is true:
  IF --force-implement flag is set:
    WARN: "⚠ Decision gate: decision_needed=true. Proceeding due to --force-implement."
    PROCEED to Phase 2.5
  ELSE:
    HALT with message:
    "✗ Decision gate: this issue has competing implementation options that require a decision.
     Run /ll:decide-issue [ISSUE_ID] to select an approach, then re-run manage-issue.
     Use --force-implement to bypass this gate."
    STOP (do not proceed to Phase 3)

ELSE (decision_needed is absent or false):
  PROCEED silently to Phase 2.5
```

---

## Phase 2.5: Confidence Gate Check

**Skip this phase if**: Action is `verify` or `plan`, `--quick` flag is set, or `config.commands.confidence_gate.enabled` is `false` (default).

When `config.commands.confidence_gate.enabled` is `true`, check the issue's `confidence_score` frontmatter before proceeding to implementation:

```
READ confidence_score from issue YAML frontmatter

IF confidence_score is absent:
  IF --force-implement flag is set:
    WARN: "⚠ Confidence gate: no confidence_score found. Proceeding due to --force-implement."
    PROCEED to Phase 3
  ELSE:
    HALT with message:
    "✗ Confidence gate: no confidence_score on file.
     Run /ll:confidence-check [ID] to evaluate readiness, or use --force-implement to bypass."
    STOP (do not proceed to Phase 3)

ELSE IF confidence_score < config.commands.confidence_gate.readiness_threshold:
  IF --force-implement flag is set:
    WARN: "⚠ Confidence gate: score [SCORE]/100 is below threshold [THRESHOLD]. Proceeding due to --force-implement."
    PROCEED to Phase 3
  ELSE:
    HALT with message:
    "✗ Confidence gate: score [SCORE]/100 is below threshold [THRESHOLD].
     Run /ll:confidence-check [ID] to evaluate readiness, or use --force-implement to override."
    STOP (do not proceed to Phase 3)

ELSE:
  LOG: "✓ Confidence gate: score [SCORE]/100 meets threshold [THRESHOLD]."
  PROCEED to Phase 3
```

---

## Phase 3a: Write Tests — Red (TDD Mode)

**Skip this phase if**: `config.commands.tdd_mode` is `false` (default), action is `verify` or `plan`, OR issue frontmatter `testable: false`.

When `config.commands.tdd_mode` is `true` and action is not `verify` or `plan`, check the issue's `testable` frontmatter field before writing tests:

```
READ testable from issue YAML frontmatter

IF testable is false:
  LOG: "⏭ Phase 3a skipped: testable: false in issue frontmatter"
  SKIP to Phase 3b (Implementation)

ELSE (testable is absent or true):
  PROCEED with Phase 3a (Write Tests — Red)
```

When proceeding, write tests BEFORE implementation:

1. **Read the plan's "Phase 0: Write Tests (Red)" section** for test specifications
2. **Write test files** based on the issue's acceptance criteria and the plan's test specifications
3. **Run tests** against the current (unmodified) codebase:

```bash
{{config.project.test_cmd}} [newly_written_test_files] -v
```

4. **Validate Red phase** — check test output:

```
RUN {{config.project.test_cmd}} on new test files

IF exit code is 0 (tests pass):
  HALT: "✗ Red phase failed: tests pass against current code.
         Tests should fail before implementation. Review test logic."
  Fix tests to properly assert expected behavior, then re-run.

IF exit code is non-zero:
  SCAN test output:
    IF output contains "FAILED" (pytest assertion failures):
      LOG: "✓ Red phase passed: tests fail with assertion errors as expected."
      PROCEED to Phase 3b (Implementation)

    IF output contains "ERROR", "ImportError", "SyntaxError", or "ModuleNotFoundError":
      HALT: "✗ Red phase invalid: tests have structural errors, not assertion failures.
             Fix import paths, syntax, or test setup before proceeding."
      Fix test code and re-run validation.
```

5. **Commit test files** (optional, if `--gates` flag is set and user approves)

> **Phase Gate** (requires `--gates` flag): After Red validation passes, pause to show test files written and validation results before proceeding to implementation.

---

## Phase 3 (3b in TDD Mode): Implement

> **TDD Mode note**: When `config.commands.tdd_mode` is `true`, this phase is Phase 3b. The goal is to make the Phase 3a tests pass (Green). After implementation, verify that all Phase 3a tests now pass before proceeding to Phase 4.

### Resuming Work (--resume flag)

If `--resume` flag is specified:

1. **Read continuation prompt** from `$(pwd)/.ll/ll-continue-prompt.md` (project-level path, if exists)
2. **Locate existing plan** matching the issue ID pattern
3. **Scan for progress** - look for `[x]` checkmarks in success criteria
4. **Present resume status** and verify previous work
5. **Continue from first unchecked item**

See [templates.md](templates.md) for the resume status display format.

### Implementation Process

1. **Create todo list** with TodoWrite
2. **Follow the plan** phase by phase
3. **Make atomic changes** - focused and minimal
4. **Mark todos complete** as you finish
5. **Update checkboxes in plan** as you complete each section

### Documentation Implementation Guidance

**IMPORTANT**: The `improve` action requires implementation, not just verification:

- For **documentation issues**: Edit or create the documentation files described in the issue
  - "Improve docs.md" means edit the file to add/update content, not review it for correctness
  - Make actual changes to improve clarity, completeness, or accuracy
  - Do not skip to verification without making file changes

- For **code issues**: Follow the same implementation process as `fix` and `implement` actions

- **All issue types**: The `improve` action is NOT a verification-only action (unlike `verify`)

### Context Monitoring & Proactive Handoff

**IMPORTANT**: Monitor context usage throughout implementation. When context is running low:

See [templates.md](templates.md) for the Session Continuation (handoff) template.

**Handoff Protocol**:

1. **Detect low context** - If you notice context approaching limits (conversation getting long, many files read), find a natural stopping point at a phase boundary.

2. **Generate handoff** - Before context exhaustion, write a continuation prompt to `$(pwd)/.ll/ll-continue-prompt.md` (absolute path derived from the current working directory — **never** to `~/.ll/ll-continue-prompt.md`) using the Session Continuation template.

3. **Signal handoff** - Output a clear message:
```
CONTEXT_HANDOFF: Ready for fresh session
Continuation prompt written to: <project-root>/.ll/ll-continue-prompt.md
To continue: Start new session with content from that file
```

4. **Stop cleanly** - Do not attempt further work after signaling handoff.

This ensures work can continue with fresh context quality rather than degraded post-compaction context.

### Implementation Guidelines
- Follow existing code patterns
- Add/update tests for changed behavior
- Keep changes focused on the issue
- Include type hints for new code
- Add docstrings for public interfaces

### Phase Gate Protocol (requires --gates)

After completing each implementation phase:

1. **Run automated verification** - Execute all automated success criteria from the plan
2. **Present pause message** - List automated checks passed and manual steps to verify
3. **Wait for human confirmation** - Do NOT proceed until confirmation received

See [templates.md](templates.md) for the phase gate pause message format.

### Default Behavior

By default (no `--gates` flag):
- Skip all phase gate pauses
- Execute all phases sequentially
- Report all results in final output
- If critical errors occur, mark as INCOMPLETE
- **Do NOT use `AskUserQuestion` or any interactive tools** — all decisions must be made autonomously

> **Note**: The `improve` action requires full implementation (Plan → Implement → Verify → Complete). Do not interpret `improve` as a verification-only action or skip the Implementation phase. For all issue types including documentation, `improve` means make changes to files, not just review or verify them.

### Mismatch Handling Protocol

When reality diverges from the plan during implementation:

1. **Detect mismatch** - File doesn't exist, code structure differs, dependencies changed
2. **Present issue clearly** - Show expected vs. actual situation
3. **With `--gates` flag**: Use AskUserQuestion with options (Adapt/Update plan/Stop)
4. **Without `--gates` flag (default)**: Do NOT use `AskUserQuestion`. Adapt if minor, mark `INCOMPLETE` if significant

See [templates.md](templates.md) for mismatch detection and reporting formats.

---

## Phase 4: Verify

Run each verification command if configured (non-null). Skip silently if not configured, reporting SKIP status.

```bash
# Run tests if test_cmd is configured (non-null)
{{config.project.test_cmd}} tests/ -v

# Run linting if lint_cmd is configured (non-null)
{{config.project.lint_cmd}} {{config.project.src_dir}}

# Run type checking if type_cmd is configured (non-null)
{{config.project.type_cmd}} {{config.project.src_dir}}

# Run build if build_cmd is configured (non-null)
{{config.project.build_cmd}}

# Run smoke test if run_cmd is configured (non-null). For long-running processes (servers), start in background, wait briefly for startup, then terminate.
{{config.project.run_cmd}}

# Run custom verification (if configured)
# {{config.commands.custom_verification}}
```

All configured checks must pass before proceeding. Unconfigured (null) checks are skipped.

---

## Phase 4.5: Integration Review

After verification passes, review new/modified code for integration quality before completing the issue.

**Skip this phase if**: Action is `verify` (verification-only mode)

### Review Checklist

For each file created or substantially modified:
1. **Duplication check** - Flag any new code duplicating existing utilities
2. **Shared module usage** - Verify imports from existing shared modules
3. **Pattern conformance** - Confirm follows project patterns
4. **Integration points** - Verify connects to existing architecture

See [templates.md](templates.md) for the Integration Report template and handling warnings guidance.

---

## Phase 5: Complete Issue Lifecycle

### 1. Update Issue File

See [templates.md](templates.md) for the Resolution section template.

### 1.5. Append Session Log Entry

Append a session log entry to the issue file before moving it. Find the current session JSONL path in `~/.claude/projects/` and add an entry.

See [templates.md](templates.md) for the Session Log entry format.

### 1.6. Inject `completed_at` Timestamp

Before moving the issue file, add a `completed_at` field to its YAML frontmatter with the current ISO 8601 UTC timestamp. Use shell `date -u +"%Y-%m-%dT%H:%M:%SZ"` format (Z-suffixed, matches the `captured_at` precedent and the Python helper `_completed_at_now()`). Use the Edit tool to insert the line into the issue's frontmatter block (after `captured_at` if present, otherwise alongside the other timestamp fields):

```yaml
---
captured_at: 2026-03-17T14:32:07Z
completed_at: 2026-03-17T15:02:41Z  # <-- new line, value from `date -u +"%Y-%m-%dT%H:%M:%SZ"`
discovered_date: 2026-03-17T00:00:00Z
---
```

This parallels the Python-driven completion paths (`ll-auto`, `ll-parallel`) that inject `completed_at` via `update_frontmatter`; the interactive path must match so all completion paths produce consistent frontmatter.

### 2. Update Issue Status

Set `status: done` using `ll-issues set-status`:

```bash
ll-issues set-status ISSUE_ID done
```

For EPIC closure, use `--cascade` to propagate the status to active children:

```bash
ll-issues set-status EPIC_ID done --cascade
```

This atomically updates the `status:` field in frontmatter without touching any other fields. Do NOT use `git mv` or the `Edit` tool to flip the status field directly — `set-status` is the canonical path and handles field preservation correctly. Do NOT move the file to a `completed/` directory — status is tracked via frontmatter.

### 3. Commit All Changes

Commit source changes and updated issue file together in a single commit:

```bash
git add [modified files] "[issue_file_path]"
git commit -m "[action]([component]): [description]

[issue_type] [ISSUE-ID]: [title]

- [change 1]
- [change 2]

Closes [ISSUE-ID]
"
```

---

## Final Report

See [templates.md](templates.md) for the Final Report template.

---

## Arguments

$ARGUMENTS

The argument schema (issue_type, action, issue_id, flags) is defined in this
file's YAML frontmatter. See [templates.md](templates.md) for the full
per-argument reference and usage examples.