req-change-workflow

---
name: "req-change-workflow"
description: "已有功能的需求变更闭环（门禁式七步）。触发硬条件：要改的功能已经实现并跑起来了。当用户说\"改需求\"\"需求变更\"\"调整交互\"\"改功能\"\"重构流程\"，或改动容易散到多个文件、碰到鉴权/存储/配置/权限、需要可靠验证 + 回滚方案时使用。流程：锁 scope 写 change brief → 从代码确认当前行为（不靠记忆和假设）→ 影响面与风险评估 + 回滚计划 → 提出新设计等用户批准（未获批准绝不动代码）→ 小而局部的 diff → 跑固定回归清单 → 更新文档和决策日志。产出：change brief + 代码 diff + 回归记录 + decision log。不适用于：全新功能从零做（走 issue-pool → design-exploration → prd-test-writer）、只改视觉样式不动任何逻辑（用 ui-design）、新想法还没定要不要做（先用 issue-pool 入池）、写 PRD/测试用例（用 prd-test-writer）、提交推送发版（用 git-push）。注意：本 skill 的七步流程通用于任何项目，但 references/regression-checklist.md 和 scripts/impact_scan.sh 目前是 Chrome 扩展专用（manifest/service worker 等）——非扩展项目照流程走，但回归清单需按该项目实际重写，不要照搬。"
license: "MIT"
---

# Req Change Workflow

## Overview

Use a lightweight, repeatable workflow to modify an existing requirement without scope creep or “边改边炸”. Produce clear artifacts at each gate so the user can approve before the implementation starts.

## Workflow (gated loop)

Follow the steps in order. Do not implement code changes until the user approves Step 4.

### Step 0: Set the plan (optional but recommended)

- Use `update_plan` to create 5–7 short steps: clarify → baseline → impact → design → implement → validate → document.
- Keep exactly one step `in_progress` at a time and advance as you finish.

### Step 1: Clarify the change (lock scope first)

Ask the user for the minimal inputs, then rewrite them into a clear “change brief”:

- Target (1 sentence): what outcome changes.
- Out of scope (1 sentence): explicitly what must NOT change.
- Acceptance criteria (3–6 bullets): observable behaviors that can be verified.
- “Must keep” constraints: compatibility, performance, security, no new dependencies, no network, etc.
- Rollback expectation: can we revert by reverting a diff, or does it require data migration/backfill?

Use the template in `references/change-brief-template.md`.

### Step 2: Confirm current behavior from code (baseline)

Do not trust memory or assumptions. Locate the real entrypoints + current data flow and summarize it in 5–10 lines:

- UI entrypoints (e.g., `sidepanel/`, `options/`) and where user actions are wired.
- Background orchestration (e.g., `service_worker.js`).
- Core modules (e.g., `src/core/...`) and storage (`src/core/local/...`).
- Config/permissions changes (e.g., `manifest.json`).

Use `scripts/impact_scan.sh` to quickly find likely files, then read only the necessary ones.

Output artifact: “Current behavior summary” + a short file list (with why each file matters).

### Step 3: Impact + risk assessment (change budget)

Before proposing a new design, list:

- Files/modules that must change and why.
- Risks: auth/session, storage migration, concurrency, caching, permission scopes, UX regressions.
- Testing checkpoints: what to verify manually (use `references/regression-checklist.md`).
- Rollback plan: what is safe to revert; what needs cleanup.

If changes touch `manifest.json` or `service_worker.js`, require a manual reload step in the validation plan (Chrome extensions cache aggressively).

Output artifact: “Impact & risk list” + “Rollback plan (1–3 bullets)”.

### Step 4: Propose the new design (get approval)

Describe the new behavior using:

- New flow (bullet sequence) including edge cases.
- State model: key states, transitions, and failure recovery.
- Change boundaries: what stays unchanged.
- Observability: logs/events/UI hints for debugging.

Then ask the user to approve:

- The acceptance criteria (Step 1) as final.
- The file list (Step 2/3) as the change budget.
- The proposed design (this step).

Do not start editing code until the user says “同意/OK/按这个做”.

### Step 5: Implement with minimal, localized diffs

Implementation rules:

- Prefer root-cause fixes over patches, but keep diffs small and focused.
- Avoid scattering logic across multiple entrypoints; centralize in one module when possible.
- Keep ES module imports explicit; avoid implicit globals.
- Add short JSDoc for exported functions when introducing new exports.
- User-visible logs: actionable Chinese messages (explain what to do next).

If the change involves async flows/cross-module calls/fallbacks, add Chinese comments explaining assumptions and failure handling.

### Step 6: Validate (fixed regression loop)

- Run the manual pages referenced in `references/regression-checklist.md`.
- If `manifest.json` or `service_worker.js` changed: reload the extension before retesting.
- Record what you tested and the observed outcome (even if it is manual).

### Step 7: Maintain (docs + decision log)

- Update project docs or inline notes for future maintainers.
- Add a short “Decision log” entry: why this design, what alternatives were rejected, and how to roll back.

Use the template in `references/decision-log-template.md`.

## Resources

### scripts/
- `scripts/impact_scan.sh`: fast file candidate scan via `rg` for keywords + common extension entrypoints.

### references/
- `references/change-brief-template.md`: input template to lock scope + acceptance criteria.
- `references/regression-checklist.md`: manual regression checklist for this repo’s Chrome extension.
- `references/decision-log-template.md`: lightweight decision record template.