pm-spec-agent

interface PmSpecResult {
  title: string;                  // "{gitmoji} {scope}: {refined one-line summary}"
  type: "feat" | "fix" | "refactor" | "chore" | "docs" | "test";
  scope: string;                   // e.g. "console-banner"
  screenTypes: ("list" | "detail" | "form")[];  // may be more than one for CRUD-shaped work
  point: 1 | 3 | 5 | 8;
  labels: string[];                // type + scope (+ priority if inferable)
  body: string;                    // 계약 블록 + 짧은 요약 — 파이프라인이 파싱하는 것(AC·범위·DoD)과 2~3줄 Summary. 아래 템플릿 참조
  narrative: string;               // 상세 기획 HTML 원고 — 사람만 읽는 서술 (배경·설계·DDR 전문). 비어 있을 수 있음
                                   //   ⚠️ body 와 narrative 를 하나로 합치지 말 것 — 어디를 옮길지
                                   //      판정할 수 없게 된다 (SoT: rules/zenhub-conventions.md
                                   //      → Issue Body HTML Contract)
  assumptions: string[];           // explicit assumptions made where input was ambiguous
                                   //   — non-design only; design judgments become designDecisions
  designDecisions?: DdrRecord[];   // settled design judgments (screen requests) — see Phase 4.5
  figmaContext?: { url: string; nodeId?: string; summary: string };
  seedSpecRef?: string;            // docs/seed-spec-*.md path if used as source of truth
}

interface DdrRecord {             // cc-designer:design-decision 의 DDR 포맷 (그 스킬이 SoT)
  id: string;                     // "DDR-01" — scope 누적 번호
  decision: string;               // 명령형 현재의 결정문 한 줄
  rung: "R1" | "R2" | "R3" | "R4" | "R5";   // 근거를 준 사다리 칸 (R0 은 결정이 아니므로 제외)
  evidence: string;               // 사실 (선례 개수 · 수치 · 스킬명) — 취향 서술 금지
  rejected?: string;              // 기각한 대안 + 이유
  reversibility: string;          // 되돌리는 방법/비용
  confidence: "high" | "medium" | "low";   // low → ⚠️ 재검토 플래그
}

## Summary
{2~3줄 — 무엇을 왜. 배경 전문은 narrative 로}

## Functional Requirements
FR-1: {requirement}
Acceptance Criteria:
- {criterion}
- {criterion}

## Scope
### In scope
- {item}
### Out of scope
- {item}

## Design Decisions
- **DDR-01** {결정문} — 근거 {R번호} {신뢰도 low 면 ⚠️ 재검토}

## Assumptions
- {assumption made where input was ambiguous}

## Background
{배경·문제 정의 — 본문 Summary 의 전문}

## Design Reference
- Figma: {url} (node {nodeId})
- Key states covered: {list}

## Design Decisions (근거 상세)
- **DDR-01** {결정문}
  - 근거 {R번호}: {사실}
  - 기각한 대안: {대안 + 이유}
  - 되돌리기: {방법/비용}

## 화면·상태 설계
{표 · 상태 전이 · 와이어프레임 설명}

Phase 1: Parse
  - Extract any URL (figma.com/design/...) from work_content
  - node-id / page params parsed from the URL query string if present
    ↓
Phase 2: Existing-spec check
  - Glob docs/seed-spec-*.md, read frontmatter/status for LOCKED
  - If found for this domain → treat as primary source of truth (don't re-derive from scratch)
    ↓
Phase 3: Design context (only if figma_url present)
  - mcp figma get_metadata / get_design_context / get_screenshot on the node
  - Degrade to text-only (+ warn) if the MCP is unavailable or the link 404s — never throw
    ↓
Phase 4: PM framing (cc-product:pm tables)
  - FR / AC per requirement
  - Scope In/Out
  - Fibonacci Story Point (1/3/5/8), matching `cc-product:pm` → "Story Point Estimation"
  - type/scope labels (explicit_options always override)
    ↓
Phase 4.5: Design decision resolution (only if screenTypes.length > 0)
  - Collect AC-blocking design questions left unanswered by seed spec (R0) and Figma context (R1)
    — empty/error/offline states, failure-notification style, input format & digits,
      copy for empty & permission-denied, target size/contrast when the mock is silent
  - Settle each via cc-designer `design-decision` (ladder R2 code precedent → R3 skills → R4 numbers → R5)
      · R2 requires an exhaustive survey of same-judgment sites — never skip to R3
      · escalation 4종(brand identity / legal-policy / irreversible / R0 conflict)만 예외:
        권고안 1개 + 근거를 body 에 남기고 그 항목만 미결로 표시 (여기서도 AskUserQuestion 은 부르지 않는다
        — 이 에이전트는 비대화형이다. 호출자인 /cc-dev:run · /cc-dev:go 가 확인 절차를 담당한다)
  - Fold results into AC + designDecisions[]; a design judgment must NOT be filed as an assumption
    ↓
Phase 5: Return PmSpecResult
  - Step 2 uses .title/.body/.labels/.point as-is
  - Step 1's requiresBdd is recomputed from .screenTypes.length > 0

1. Step 1 produces initial_analysis (type/screen judged by meaning — Jev reflex first — plus scope/point)
   ↓
2. pm-spec-agent called with work_content + initial_analysis + explicit_options + figma_url + locked_seed_spec
   ↓
3. PmSpecResult returned
   - analysis.type/scope/point updated (explicit_options win where given)
   - analysis.issueBody = PmSpecResult.body
   - analysis.narrative = PmSpecResult.narrative (Step 2 가 20행 초과 여부로 가르고, 넘으면 Step 4-5 가 HTML 로 커밋)
   ↓
4. Step 2 creates the ZenHub issue using PmSpecResult verbatim