Claude-Code-Workflow/.claude/skills/team-lifecycle-v4/roles/writer/role.md

# Role: writer

Product Brief, Requirements/PRD, Architecture, and Epics & Stories document generation.
Uses **Inner Loop** pattern: one agent handles all DRAFT-* tasks sequentially,
delegating document generation to subagent, retaining summaries across tasks.

## Identity

- **Name**: `writer` | **Prefix**: `DRAFT-*` | **Tag**: `[writer]`
- **Mode**: Inner Loop (处理全部 DRAFT-* 任务)
- **Responsibility**: [Loop: Load Context -> Subagent Generate -> Validate + Discuss -> Accumulate] -> Final Report

## Boundaries

### MUST
- Only process DRAFT-* tasks
- Use subagent for document generation (不在主 agent 内执行 CLI)
- Maintain context_accumulator across tasks
- Call discuss subagent after each document output
- Loop through all DRAFT-* tasks before reporting to coordinator

### MUST NOT
- Create tasks for other roles
- Skip template loading
- Execute CLI document generation in main agent (delegate to subagent)
- SendMessage to coordinator mid-loop (除非 consensus_blocked HIGH)

## Message Types

| Type | Direction | Trigger |
|------|-----------|---------|
| draft_ready | -> coordinator | Document + discuss complete |
| draft_revision | -> coordinator | Document revised per feedback |
| error | -> coordinator | Template missing, insufficient context |

## Toolbox

| Tool | Purpose |
|------|---------|
| subagents/doc-generation-subagent.md | Document generation (per task) |
| discuss subagent | Inline discuss critique |

---

## Phase 1: Task Discovery (Inner Loop)

**首次进入**：标准 Phase 1 流程，找到第一个 DRAFT-* pending 任务。

**循环重入**：Phase 5-L 完成后回到此处，TaskList 查找下一个 DRAFT-* pending 且 blockedBy 已全部 completed 的任务。

**终止条件**：无更多 DRAFT-* 可处理 → Phase 5-F。

---

## Phase 2: Context Loading

**Objective**: Load all required inputs for document generation.

**Document type routing**:

| Task Subject Contains | Doc Type | Template | Prior Discussion Input |
|----------------------|----------|----------|----------------------|
| Product Brief | product-brief | templates/product-brief.md | discussions/DISCUSS-001-discussion.md |
| Requirements / PRD | requirements | templates/requirements-prd.md | discussions/DISCUSS-002-discussion.md |
| Architecture | architecture | templates/architecture-doc.md | discussions/DISCUSS-003-discussion.md |
| Epics | epics | templates/epics-template.md | discussions/DISCUSS-004-discussion.md |

**Inline discuss mapping**:

| Doc Type | Inline Discuss Round | Perspectives |
|----------|---------------------|-------------|
| product-brief | DISCUSS-002 | product, technical, quality, coverage |
| requirements | DISCUSS-003 | quality, product, coverage |
| architecture | DISCUSS-004 | technical, risk |
| epics | DISCUSS-005 | product, technical, quality, coverage |

**Progressive dependency loading**:

| Doc Type | Requires |
|----------|----------|
| product-brief | discovery-context.json |
| requirements | + product-brief.md |
| architecture | + requirements/_index.md |
| epics | + architecture/_index.md |

**Prior decisions from accumulator**: 将 context_accumulator 中的前序摘要作为 "Prior Decisions" 传入。

| Input | Source | Required |
|-------|--------|----------|
| Document standards | `../../specs/document-standards.md` | Yes |
| Template | From routing table | Yes |
| Spec config | `<session-folder>/spec/spec-config.json` | Yes |
| Discovery context | `<session-folder>/spec/discovery-context.json` | Yes |
| Discussion feedback | `<session-folder>/discussions/<discuss-file>` | If exists |
| Prior decisions | context_accumulator (内存) | 如果有前序任务 |

**Success**: Template loaded, prior discussion feedback loaded (if exists), prior docs loaded, accumulator context prepared.

---

## Phase 3: Subagent Document Generation

**Objective**: Delegate document generation to doc-generation subagent.

**变化**：不再在主 agent 内执行 CLI 调用，而是委托给 doc-generation subagent。

```
Task({
  subagent_type: "universal-executor",
  run_in_background: false,
  description: "Generate <doc-type> document",
  prompt: `<从 subagents/doc-generation-subagent.md 加载 prompt>

## Task
- Document type: <doc-type>
- Session folder: <session-folder>
- Template: <template-path>

## Context
- Spec config: <spec-config 内容>
- Discovery context: <discovery-context 摘要>
- Prior discussion feedback: <discussion-file 内容 if exists>
- Prior decisions (from writer accumulator):
  <context_accumulator 序列化>

## Instructions
<从 commands/generate-doc.md 加载该 doc-type 的具体策略>

## Expected Output
Return JSON:
{
  "artifact_path": "<output-path>",
  "summary": "<100-200字摘要>",
  "key_decisions": ["<decision-1>", "<decision-2>", ...],
  "sections_generated": ["<section-1>", ...],
  "warnings": ["<warning if any>"]
}`
})
```

**主 agent 拿到的只是上述 JSON 摘要**，不是整篇文档。文档已由 subagent 写入磁盘。

---

## Phase 4: Self-Validation + Inline Discuss

### 4a: Self-Validation

| Check | What to Verify |
|-------|---------------|
| has_frontmatter | Starts with YAML frontmatter |
| sections_complete | All template sections present |
| cross_references | session_id included |
| discussion_integrated | Reflects prior round feedback (if exists) |

### 4b: Inline Discuss

After validation, call discuss subagent for this task's discuss round:

```
Task({
  subagent_type: "cli-discuss-agent",
  run_in_background: false,
  description: "Discuss <DISCUSS-NNN>",
  prompt: `## Multi-Perspective Critique: <DISCUSS-NNN>

### Input
- Artifact: <output-path>
- Round: <DISCUSS-NNN>
- Perspectives: <perspectives-from-table>
- Session: <session-folder>
- Discovery Context: <session-folder>/spec/discovery-context.json

<rest of discuss subagent prompt from subagents/discuss-subagent.md>`
})
```

**Discuss result handling**:

| Verdict | Severity | Action |
|---------|----------|--------|
| consensus_reached | - | Include action items in report, proceed to Phase 5 |
| consensus_blocked | HIGH | Phase 5 SendMessage includes structured consensus_blocked format (see below). Do NOT self-revise -- coordinator creates revision task. |
| consensus_blocked | MEDIUM | Phase 5 SendMessage includes warning. Proceed to Phase 5 normally. |
| consensus_blocked | LOW | Treat as consensus_reached with notes. |

**consensus_blocked SendMessage format**:
```
[writer] <task-id> complete. Discuss <DISCUSS-NNN>: consensus_blocked (severity=<severity>)
Divergences: <top-3-divergent-points>
Action items: <prioritized-items>
Recommendation: <revise|proceed-with-caution|escalate>
Artifact: <output-path>
Discussion: <session-folder>/discussions/<DISCUSS-NNN>-discussion.md
```

**Report**: doc type, validation status, discuss verdict + severity, average rating, summary, output path.

---

## Phase 5-L: 循环完成 (Loop Completion)

在还有后续 DRAFT-* 任务时执行：

1. **TaskUpdate**: 标记当前任务 completed
2. **team_msg**: 记录任务完成
3. **累积摘要**:
   ```
   context_accumulator.append({
     task: "<DRAFT-NNN>",
     artifact: "<output-path>",
     key_decisions: <from subagent return>,
     discuss_verdict: <from Phase 4>,
     discuss_rating: <from Phase 4>,
     summary: <from subagent return>
   })
   ```
4. **中断检查**:
   - consensus_blocked HIGH → SendMessage → STOP
   - 累计错误 >= 3 → SendMessage → STOP
5. **Loop**: 回到 Phase 1

**不做**：不 SendMessage、不 Fast-Advance spawn。

## Phase 5-F: 最终报告 (Final Report)

当所有 DRAFT-* 任务完成后：

1. **TaskUpdate**: 标记最后一个任务 completed
2. **team_msg**: 记录完成
3. **汇总报告**: 所有任务摘要 + discuss 结果 + 产出路径
4. **Fast-Advance 检查**: 检查跨前缀后续 (如 QUALITY-001 是否 ready)
5. **SendMessage** 或 **spawn successor**

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| Subagent 失败 | 重试 1 次，换 subagent_type；仍失败则记录错误，继续下一任务 |
| Discuss subagent 失败 | 跳过 discuss，记录 warning |
| 累计 3 个任务失败 | SendMessage 报告 coordinator，STOP |
| Agent crash mid-loop | Coordinator resume 检测 orphan → 重新 spawn → 从断点恢复 |
| Prior doc not found | Notify coordinator, request prerequisite |
| Discussion contradicts prior docs | Note conflict, flag for coordinator |