/issue-assessment

description: Read a GitHub issue, perform an independent assessment, and present findings
argument-hint: <issue-number> [context]
allowed-tools: Bash, Read, Grep, Glob, Task, AskUserQuestion

Issue Assessment

You are performing an independent assessment of a GitHub issue. Your goal is to deeply understand the issue, explore the relevant codebase, and present your findings with a recommended next step.

**User input:** $ARGUMENTS

**Note:** This command performs best with an Opus-class model. On Sonnet or Haiku, results may be shallower.

Step 1: Parse Input

The user's input contains:

• An **issue number** (required)
• Additional **context** or constraints (optional)

Extract the issue number from the input. If the input is ambiguous, ask the user to clarify. If context was provided, note it for use in Steps 3-4.

Step 2: Read the Issue

Read the issue title and body:

gh issue view <issue-number>

Then read all comments (`--comments` returns only comments and silently drops the title and body, so both calls are required):

gh issue view <issue-number> --comments

Parse and understand:

• The problem statement
• Any constraints or requirements mentioned
• Prior discussion or decisions in the comments
• Acceptance criteria (if specified)
• Current state of the issue (open, closed, linked PRs, etc.)

Step 3: Explore the Codebase

Launch 5 exploration agents of type `feature-dev:code-explorer` in parallel by delegating to subagents. Each agent should trace through the code comprehensively and target a different aspect. All lenses are required -- Step 4 always evaluates risks and critical premises, so their corresponding evidence-gathering lenses must always run:

• **Relevant code**: Find existing code related to the issue. Trace through their implementation comprehensively, identifying patterns, conventions, and the design decisions that shaped them.
• **Architecture**: Map the relevant architecture layers, abstractions, and data flow, tracing through the code comprehensively to understand how components interact and where boundaries lie.
• **Prior work**: Check for related branches, PRs, or commits that may already address part of the issue. Trace through any partial implementations to assess their completeness and approach.
• **Counter-evidence**: Look for codebase evidence that challenges the issue's premise or proposed approach. Identify existing patterns, design decisions, or prior solutions that suggest a different approach, reveal the issue may be addressing symptoms rather than root causes, or indicate the problem is a special case of something more general.
• **Constraints and edge cases**: Investigate what could go wrong with the proposed approach. Look for failure modes, boundary conditions, implicit assumptions, and pitfalls in the affected code areas.

Do not run these subagents in the background. For parallel execution, launch them in a single message instead.

If the user provided context, include it in each agent's prompt to focus exploration on the user's areas of concern.

Each agent should return a list of 5-10 key files. After agents complete, read all identified files to build deep understanding.

Step 4: Assess

If the user provided context in Step 1, ensure your assessment explicitly engages with their areas of concern in the relevant categories below. The user's focus should be visible in the matching section (e.g., a backward-compatibility concern surfaces in Risks; a scoping concern surfaces in Scope or Gaps; a premise challenge surfaces in Critical evaluation). Do not omit other categories to make room -- the user's focus weights the depth of coverage, not the breadth.

Based on your understanding of the issue and codebase, present your assessment to the user:

1. **Summary**: What the issue is asking for in your own words. 2. **Current state**: What exists today in the codebase that is relevant. 3. **Gaps**: What is missing, broken, or unclear. 4. **Ambiguities**: Any underspecified aspects, contradictions, or open questions in the issue. 5. **Scope**: Your assessment of the size and complexity of the work. 6. **Risks**: Potential pitfalls, edge cases, or architectural concerns. If exploration did not surface risk-relevant evidence, state that no significant risks were identified rather than manufacturing concerns. 7. **Critical evaluation**: Evaluate the issue's premise and proposed approach against codebase evidence and established engineering principles. This category challenges whether the issue is asking for the right thing -- distinct from Ambiguities (underspecified aspects of the issue) and Risks (pitfalls assuming the issue is valid). Challenge only when grounded in evidence or principle -- do not speculate. All claims must be backed by specific references: cite files or patterns for codebase-based challenges; cite established engineering principles or widely-known patterns for principle-based challenges.

• Whether the codebase suggests a different or better approach than what the issue proposes
• Whether the proposed change creates redundancy, conflicts, or maintenance burden given existing code
• Whether the issue addresses symptoms rather than the root cause
• Whether a more elegant design achieves the same goal with less complexity
• Whether the problem generalizes beyond the reporter's specific case -- a special case of a broader problem worth solving generally

If codebase exploration did not surface evidence relevant to evaluating the premise, state that no counter-evidence was found rather than manufacturing concerns. Do not make scheduling or prioritization judgments.

Step 4a: Track Interaction Findings

From this point forward through Step 6, track any substantive findings that emerge from your interaction with the user. These include:

• **Reframed problems**: The user corrects or reframes the issue's core problem
• **Resolved ambiguities**: Answers to open questions surfaced in Step