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

•
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.
•
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.
•
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.
•
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.
•
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.
•
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.
•
Walk through the ExecPlan at a high level:
- •Rephrase the plan into a short ordered narrative (typically 5-10 steps).
- •For each step: what changes, where (file paths), why it exists, and what proof (test/manual) makes it safe.
•
Identify the dangerous parts (risk hotspots):
- •Focus on risks that can cause production incidents: cross-module coupling, DTO/JSON mismatches, vendor contract semantics, transactional/persistence ordering, "changed detection" logic, UI state desync, test fragility.
- •For each risk: severity (High/Med/Low), failure mode, how to detect it (tests/logs/manual), and mitigation/guardrails.
•
Provide a concise validation and rollout note:
- •The exact commands to run (build/tests) and what success looks like.
- •The highest-signal manual scenario(s) to prove the new behavior.
•
Add an optional "Reviewer Notes / Human Supervision" section for human oversight; keep it short and explicit (risk acceptance, approvals, rollout constraints).

Output format

Use the template in assets/issue_plan_brief_template.md as the skeleton for your response. Keep each section to 3-5 bullets or short sentences; favor precision over verbosity.

Guardrails

•Prefer file/symbol references over large pasted code.
•Do not invent behavior. If unsure, inspect the repository and state assumptions explicitly.
•Keep the brief focused on the specific issue/plan; avoid drive-by refactors or unrelated recommendations.