---
name: change-writer
description: "Write change proposals with impact analysis following OpenLogos delta workflow. Use when the project lifecycle is active and source code or methodology documents need modification."
---

# Skill: Change Writer

> Assist in writing change proposals — analyze the scope of change impact, generate a structured proposal.md and a phase-based tasks.md, ensuring changes are traceable and impact is controllable.

## Trigger Conditions

- User has just run `openlogos change <slug>` and wants AI help filling in the proposal
- User describes a need to modify, add, or remove a scenario/feature
- User mentions "change proposal", "iteration", "requirement change"

## Prerequisites

1. Project is initialized (`logos/logos.config.json` exists)
2. Change proposal directory has been created by CLI (`logos/changes/<slug>/` exists)
3. Main documents are readable (effective documents exist in `logos/resources/`)

If prerequisites are not met, prompt the user to run `openlogos change <slug>` to create the proposal directory first.

## Core Capabilities

1. Understand the user's intended change
2. Scan existing documents in `logos/resources/` to identify the affected scope
3. Determine the change type based on change propagation rules (Requirement-level / Design-level / Interface-level / Code-level)
4. Generate a compliant proposal.md
5. Automatically break down tasks.md by change type

## Execution Steps

### Step 1: Understand the Change Intent

Confirm the following information with the user (ask follow-up questions if insufficient, up to 2 rounds):

- **What is the change**: What needs to be added, modified, or removed?
- **Reason for the change**: Why is this change needed? Is it from requirement feedback, a bug, or an optimization?
- **Related scenarios**: Which existing scenario IDs are involved (S01, S02...)?

### Step 2: Analyze the Impact Scope

Scan documents in `logos/resources/` to determine the impact scope:

1. Read requirement documents (`prd/1-product-requirements/`) to check related scenario definitions
2. Read product design (`prd/2-product-design/`) to check related functional specs and prototypes
3. Read technical plans (`prd/3-technical-plan/`) to check related sequence diagrams
4. Read API documents (`api/`) to check related endpoints
5. Read DB documents (`database/`) to check related table structures
6. Read orchestration tests (`scenario/`) to check related test cases

### Step 3: Determine the Change Type

Refer to change propagation rules to determine the change type and minimum update scope:

| Change Type | Minimum Updates Required |
|-------------|------------------------|
| Requirement-level change | Full chain (Requirements → Design → Architecture → API/DB → Orchestration → Code) |
| Design-level change | Prototypes + Scenarios + API/DB + Orchestration + Code |
| Interface-level change | API/DB + Orchestration + Code |
| Code-level fix | Code + Re-verification |

### Step 4: Generate proposal.md

Generate using the following template and write to `logos/changes/<slug>/proposal.md`:

```markdown
# Change Proposal: [Change Name]

## Reason for Change
[Why is this change needed? What requirement/feedback/bug does it originate from?]

## Change Type
[Requirement-level / Design-level / Interface-level / Code-level]

## Change Scope
- Affected requirement documents: [List, down to filename and section]
- Affected functional specs: [List]
- Affected business scenarios: [Scenario ID list]
- Affected APIs: [Endpoint list]
- Affected DB tables: [Table name list]
- Affected orchestration tests: [List]

## Change Summary
[Describe in 1-3 paragraphs what specifically will change]
```

### Step 5: Generate tasks.md

Automatically break down the task checklist based on the change type and impact scope. Only list the phases that need updating:

```markdown
# Implementation Tasks

## Phase 1: Document Changes
- [ ] Output delta file to `deltas/prd/1-product-requirements/` — Update acceptance criteria for S0x in requirement documents
- [ ] Output delta file to `deltas/prd/1-product-requirements/` — Add/modify scenario in the scenario overview table

## Phase 2: Design Changes
- [ ] Output delta file to `deltas/prd/2-product-design/1-feature-specs/` — Update interaction design for S0x in functional specs
- [ ] Output delta file to `deltas/prd/2-product-design/2-page-design/` — Update prototypes

## Phase 3: Technical Changes
- [ ] Output delta file to `deltas/prd/3-technical-plan/1-architecture/` — Update technical architecture
- [ ] Output delta file to `deltas/prd/3-technical-plan/2-scenario-implementation/` — Update sequence diagram for S0x
- [ ] Output delta file to `deltas/api/` — Update API YAML
- [ ] **Validate API YAML** — all files in `logos/resources/api/` must be valid YAML and valid OpenAPI 3.x (all `description`/`summary` values containing `:` or special chars must be double-quoted)
- [ ] Output delta file to `deltas/database/` — Update DB DDL
- [ ] Output delta file to `deltas/scenario/` — Update orchestration test cases
- [ ] Implement code changes (modify `src/` directly — no delta needed)
```

### Step 6: Output Delta Files

**When to trigger**: After tasks.md is filled in and the user has confirmed the proposal, produce delta files item by item per the task checklist.

#### Directory Mapping

Delta files are written to the corresponding subdirectory under `logos/changes/<slug>/deltas/`, mirroring the `logos/resources/` structure:

| Target main document directory | Delta subdirectory |
|---|---|
| `logos/resources/prd/` | `deltas/prd/` |
| `logos/resources/api/` | `deltas/api/` |
| `logos/resources/database/` | `deltas/database/` |
| `logos/resources/scenario/` | `deltas/scenario/` |

`prd/` subdirectories map as follows:

| Target main document subdirectory | Delta subdirectory |
|---|---|
| `logos/resources/prd/1-product-requirements/` | `deltas/prd/1-product-requirements/` |
| `logos/resources/prd/2-product-design/1-feature-specs/` | `deltas/prd/2-product-design/1-feature-specs/` |
| `logos/resources/prd/2-product-design/2-page-design/` | `deltas/prd/2-product-design/2-page-design/` |
| `logos/resources/prd/3-technical-plan/1-architecture/` | `deltas/prd/3-technical-plan/1-architecture/` |
| `logos/resources/prd/3-technical-plan/2-scenario-implementation/` | `deltas/prd/3-technical-plan/2-scenario-implementation/` |

Code implementation (`src/`, `test/`) does **not** produce delta files — modify source files directly.

#### File Naming

Use the **same name** as the target main document (including subdirectory levels). For example:
- Target: `logos/resources/api/core-api.yaml` → delta: `deltas/api/core-api.yaml`
- Target: `logos/resources/prd/1-product-requirements/core-01-requirements.md` → delta: `deltas/prd/1-product-requirements/core-01-requirements.md`

#### File Format

Each delta file uses `ADDED / MODIFIED / REMOVED` markers, with each block corresponding to one section in the main document:

```markdown
## ADDED — [New section title]
[Complete content to add]

## MODIFIED — [Modified section title]
[Complete updated content — replaces the same-named section in the main document during merge]

## REMOVED — [Deleted section title]
[Explain the reason for deletion — the same-named section will be removed from the main document during merge]
```

#### Behavioral Rules

- After completing each delta file, immediately update the corresponding item in `tasks.md` from `[ ]` to `[x]`
- **Do NOT directly modify documents under `logos/resources/`** — all spec changes must go through delta files and be merged via `openlogos merge`
- After all deltas are produced, remind the user to explicitly authorize running `openlogos merge <slug>`

### Step 7: Guide Follow-up Actions (Chain-driven)

Provide a ready-to-use prompt that allows the user to kick off chain execution of all tasks with a single command:

- **Requirement-level / Design-level changes** (multiple tasks): Suggest the user say "Follow tasks.md and help me progressively update all affected documents for S0x"
- **Code-level fixes** (fewer tasks): Suggest the user say "Help me fix the [issue description] for S0x and re-verify"

Chain execution behavior rules:
1. AI reads `tasks.md` and executes items sequentially
2. **After completing each task, immediately update that item in `tasks.md` from `[ ]` to `[x]`** (AI does this proactively — no user reminder needed)
3. After completing each task, report a summary of changes and automatically prompt "Continue to the next item?"
4. After the user says "Continue" or provides adjustments, proceed to the next item
5. After all tasks are completed, remind the user to explicitly authorize running `openlogos merge <slug>`

**Key principle**: Do not make the user manually track the task checklist — AI should proactively drive the process.

**`openlogos merge` and `openlogos archive` are human confirmation points**:
- AI must not execute these commands without explicit user authorization
- When the user explicitly requests execution (including via `/openlogos:merge` or `/openlogos:archive` slash commands), AI may execute them
- Must not be triggered implicitly in scenarios like "continue", "finish up", or "follow the process"

AI is only responsible for driving content modifications and must not advance proposal state without explicit authorization.

## Output Specification

- File format: Markdown
- Storage location: `logos/changes/<slug>/`
- Filenames: `proposal.md` and `tasks.md` (overwrite the CLI-generated templates)

## Best Practices

- **Overestimate the impact scope**: Missing an update in one link is more dangerous than double-checking
- **Change type determines workload**: Help users understand before they start that changing one requirement may require a full-chain update
- **tasks.md is the execution checklist**: Check off each item with `[x]` upon completion for easy progress tracking
- **Follow the process even for small changes**: A change that appears to be "just one API line" may affect orchestration tests and code

## Recommended Prompts

The following prompts can be copied directly for use with AI:

**Fill in proposal**:
- `Help me fill in the change proposal <slug>`
- `I want to add a "remember password" feature to the S02 login scenario, help me analyze the impact scope`
- `This bug fix only involves the code layer, help me quickly write a proposal`

**Execute tasks (after proposal is completed)**:
- `Follow tasks.md and help me progressively update all affected documents for S02`
- `Help me fix the 500 error on the S02 login endpoint and re-verify`