issue-plan-brief

Issue Plan Brief

Overview

Produce a detailed, skimmable tech lead brief for an issue card and its ExecPlan: what the system does today, what we want it to do, how the plan achieves that, where code will change, and what could go wrong.

Inputs (required)

• ISSUE_PATH: Repository-relative path to the issue card Markdown file.
• EXECPLAN_PATH: Repository-relative path to the ExecPlan Markdown file.

If either path is missing or ambiguous, ask the user for it before proceeding.

Procedure

1. Read AGENTS.md and PLANS.md (repo root) to orient on architecture and constraints, but do not turn this into an alignment audit. If you discover misalignment blockers, stop after "Executive Summary" and add "Alignment gaps: run align-issue-card" in the output.

2. Read ISSUE_PATH fully and extract:

   • Outcomes (user-visible behavior), Problem statement, Investigation findings, Definitions.
   • In-scope requirements + non-goals.
   • Acceptance criteria + verification plan.
   • Prior art file list and any related issues.

3. Read EXECPLAN_PATH fully and extract:

   • Purpose / Big picture, Context and orientation, Plan of work, Concrete steps, Validation and acceptance.
   • Interfaces/dependencies and any decision log entries.

4. Confirm "what we have" with evidence:

   • Use the issue's prior-art pointers to open the 1-3 most relevant production files and verify the current behavior described by the issue card (don't rely on assumptions).
   • Summarize current state as behavior + data flow + key code anchors (paths + type/function names), not as a prose dump.

5. Summarize "what we want":

   • Restate desired outcomes in user-visible terms.
   • Enumerate new/changed data fields and contracts that cross boundaries (backend <-> client, persistence, vendor integration).
   • Explicitly restate non-goals to constrain scope.

6. Describe the "overall implementation proposal" (the schema):

   • Write an end-to-end flow that connects the change from input -> mapping/logic -> API -> UI -> persistence/guards -> observable outputs/errors.
   • Call out the key invariants the implementation must preserve (e.g., "no persisted changes on blocked flow", "backwards compatible JSON", "no silent fallbacks").
   • Name the concrete touched layers/modules/projects in this repo and their responsibilities.
   • List the main file touchpoints and what each contributes (add field, map it, render it, block edit, add tests).
   • Provide a compact "critical contracts" list (DTOs, JSON fields, public interfaces) that must stay consistent.