emoon-backend/.agents/skills/requirement-lifecycle-manager/SKILL.md

---

name: requirement-lifecycle-manager

description: Guide the emoon-backend team through its Docs as Code and Git branch lifecycle. Use when starting or advancing a requirement, assigning or checking a feature_id, auditing document gaps, deciding whether work may enter development or merge, creating or checking docs/feature/hotfix/closeout branches, or coordinating requirement documents, reviews, tests, acceptance, and archive records with Git gates.

Requirement Lifecycle Manager

Act as the project-manager layer for requirements. Keep documents, lifecycle state, and Git branches aligned without imposing detailed commit conventions.

Required Context

Always read:

1. docs/文档中心.md
2. docs/governance/文档分类.md
3. docs/governance/元数据规范.md
4. docs/governance/生命周期流程.md

When explaining or operating the team workflow, also read 开发协作说明.md in this skill directory.

When a feature_id is known, read docs/initiatives/<feature_id>/专题索引.md and every existing document it references.

Before any Git action, inspect the current branch, worktree, remotes, and divergence from origin/master. Do not treat a locally-ahead master as the stable baseline.

Document Lifecycle

Inspect stages in this order:

1. 需求录入.md
2. 需求文档.md
3. 概要设计.md
4. 详细设计.md
5. ADR when triggered
6. API contract when triggered
7. implementation plan and 开发进度.md
8. 测试计划.md
9. 测试结果.md
10. closeout in 专题索引.md

Allow a stage to be skipped only when the initiative index records the reason, risk, replacement record, and follow-up requirement.

Branch Lifecycle

Use one shared feature branch per requirement:

docs/FEAT-YYYYMM-NNN-short-name
  -> master
  -> feature/FEAT-YYYYMM-NNN-short-name
  -> master
  -> docs/FEAT-YYYYMM-NNN-short-name-closeout
  -> master

• Protect master: never commit directly to it.
• Prepare and review initial requirement documents on docs/<feature_id>.
• Merge approved documents to master before development.
• Create the shared feature/<feature_id> only after ready_for_development passes, from the recorded origin/master commit.
• Let team members commit directly to the shared feature branch. Do not require task branches or detailed commit-message conventions.
• Never rebase or force-push a published shared feature branch. Merge master into it when synchronization is needed.
• Before final review, merge the latest origin/master into the feature branch and rerun required verification.
• Merge feature/<feature_id> to master through a reviewed PR using a merge commit; do not squash or rebase.
• After merge, use docs/<feature_id>-closeout to record the merge SHA, final status, test conclusion, and remaining issues. Then the remote feature branch may be deleted with explicit authorization.

Feature branches must not merge into each other. Record cross-feature dependencies by feature_id; normally wait for the dependency to reach master. For necessary parallel verification, use a disposable integration/<feature-a>-<feature-b> branch that never merges directly to master.

Development Gate

Treat ready_for_development as a hard gate. Require:

• approved intake and PRD with acceptance criteria and non-goals;
• all triggered outline design, detailed design, ADR, API, and security documents approved;
• approved test plan and an actionable implementation plan;
• no blocking unresolved question in the initiative index;
• clean worktree and confirmed synchronization with origin/master;
• proposed branch name and exact baseline commit SHA recorded in the initiative index.

If the gate fails, do not create or push the feature branch. Report the missing prerequisites and offer to complete them, formally record a permitted skip, or keep the work exploratory.

Merge Gate

Treat ready_for_merge as a hard gate. Require:

• latest origin/master merged into the feature branch with no unresolved conflict;
• requirements, acceptance criteria, implementation, and required documents aligned;
• planned tests executed and 测试结果.md records passes, failures, residual risks, and conclusion;
• required Maven compile, module tests, and applicable AiPlatformArchitectureTest passed;
• no blocking defect, security issue, or unresolved interface-contract difference;
• human review of the feature-to-master PR.

Do not use commit style, commit count, or history tidiness as merge gates.

Change, Pause, and Exception Rules

• Keep minor implementation-time document corrections on the feature branch.
• For material scope, acceptance, API, data, security, or architecture changes, pause affected implementation, update documents on the feature branch, and rerun the applicable gate.
• Create a new feature_id when a change becomes an independent requirement.
• Use initiative state paused for resumable work and keep its remote feature branch. On resume, synchronize master and revalidate documents and gates.
• Use initiative state cancelled for abandoned work. Never merge incomplete code to master; normally delete its feature branch after preserving any explicitly required record.
• For production emergencies, allow hotfix/<short-name> from master with a lightweight gate: incident description, fix scope, and verification result. Merge through PR, then backfill or link the appropriate feature_id records.

Git Authorization

Read-only inspection and gate evaluation need no extra confirmation. Generating names and commands is also safe.

Require explicit user authorization before creating a branch, committing, pushing, creating or merging a PR, deleting a branch, or otherwise changing remote state. Never automatically merge master, force-push, or delete a remote branch. A general instruction to advance the lifecycle authorizes ordinary safe steps, but obtain confirmation again for push, PR merge, and remote branch deletion.

Triage and Output

When asked what to do next:

1. Identify the feature_id and initiative.
2. Inventory document types, statuses, required triggered artifacts, branch state, and recorded SHAs.
3. Evaluate the current document stage and the applicable Git gate.
4. Report the smallest next action and any prohibited transition.

Use this response shape:

当前阶段：...
当前分支：...
已有文档：...
Gate 状态：...
缺口：...
下一步：...
建议动作：...
警示：...

Document Creation

Use templates under docs/templates/. Keep Chinese human-readable filenames; keep identifiers and lifecycle state in Front Matter. Fill doc_id, feature_id, type, title, status, owner, created_at, updated_at, related documents, and affected modules, then update 专题索引.md.

Never silently skip a document or Git gate.