SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscs-feat-design-review

cs-feat-design-review

Coding & development

View repository

Updated 10-15 20:30

About this skill

cs-feat-design-review

Required reading at startup

Before any judgment or action, first execute the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not substitute by reading external AI entry points (see .codestable/reference/execution-conventions.md）。

This stage is the solution review gate before the feature design is handed to the user for manual confirmation. It only reads the design, checklist, related documents, and necessary code facts, and only writes {slug}-design-review.md; it does not directly modify the design/checklist, does not approve the design on the user's behalf, and does not enter implementation.

The goal is not to make product judgments on the user's behalf, but to confirm that this design already has the conditions for the user to review effectively and for downstream stages to execute stably: requirement boundaries are verifiable, the noun layer and orchestration layer are backed by code facts, steps can be independently verified, checks can be traced back to design evidence, and risks / baselines / deliverables / cleanliness can be consumed by subsequent implement, code review, QA, and acceptance.

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md. The specific structure of the feature design is subject to the target {slug}-design.md / {slug}-checklist.yaml and the shared conventions within the project. Report language: the body of the design-review report must follow .codestable/attention.md inChinese; if the draft is in English, rewrite it into Chinese before writing to disk. frontmatter / yaml fields are not translated.

Inputs

Before entering review, you must read:

  • .codestable/attention.md
  • .codestable/features/{feature}/{slug}-design.md
  • .codestable/features/{feature}/{slug}-checklist.yaml
  • The {slug}-intent.md / {slug}-brainstorm.mdin the same directory (if it exists)
  • The requirement document pointed to by the design frontmatter
  • The roadmap main document and items.yaml pointed to by the design frontmatter (if there is roadmap / roadmap_item）
  • The architecture document pointed to by section 4 of the design
  • Related compound accumulation: use the project search tool to search for decision / learning / explore / trick by feature keywords
  • Key code locations, interfaces, types, components, commands, and configurations referenced in the design
  • Independent Task agent reviewer output (if started in this round)

When there are no code references, do not force a full repository scan; but when the design claims to reuse, modify, mount onto, or constrain an existing module, you must read the corresponding code or documentation facts to verify.

Startup check

  1. The design exists, the frontmatter doc_type=feature-design，feature is consistent with the directory,status is usually draft; when re-reviewing an already approved design, confirm that the user has indeed requested re-review.
  2. The checklist exists,feature is consistent with the directory,steps is non-empty,checks is non-empty; if the checklist is missing, report blocked, go back to cs-feat-design to generate the review candidate checklist.
  3. The checklist's steps.status and checks.status should both be pendingbefore human review; an existing done/passed indicates stage confusion, report blocked。
  4. When starting from the roadmap, the roadmap item must be findable in items.yaml, and the design's roadmap_item must align with the feature slug.
  5. If there is already {slug}-design-review.md：
    • status: passed and the design/checklist have not changed: prompt that it can proceed to the user's overall review.
    • status: changes-requested / blocked: read the old findings and confirm whether to re-review.
    • The design/checklist have changed: re-review, and record the round in the report.

Independent Task agent reviewer gate

At this stage, an independent Task agent reviewer must be started first; the current agent's local review can only serve as merge and fact verification, and cannot replace independent review. Only when the runtime truly has no Task agent capability, the provider is unavailable and cannot be configured, or the user explicitly authorizes it after seeing the degradation risk, is it permitted local-only / skipped-by-user. Batch design, being in a hurry, and the main agent considering the risk low are not grounds for degradation; when authorization for degradation is needed, first follow .codestable/reference/approval-conventions.md to write approval-report.md, then let the user choose.

Once an independent Task agent reviewer should be started or has been started in this round, it is the input to this round's review gate. The main agent may first produce a local review draft, but cannot finalize before the reviewer returns {slug}-design-review.md, cannot give passed, and cannot hand the design to the user for confirmation. If the reviewer is stuck, fails, is blocked by permissions, or takes too long, this round can only be marked as blocked / independent-review-pending, letting the user decide to continue waiting, retry the reviewer, or explicitly degrade to local-only review.

Detection is self-checked by the main agent at runtime against its own tools, not guessed by a script about the environment — the main agent knows best which tools it has on hand. Start an independent Task agent reviewer according to the Task agent selection rules (prefer Paseo subagent, otherwise the current host's native Codex/Claude Task/Agent):

  1. Has the mcp__paseo__create_agent tool: must preferentially use the Paseo subagent for read-only independent review (first choice: can switch provider to achieve truly heterogeneous review). Before starting, first load / read the current description of the paseo skill, and follow its rules: read ~/.paseo/orchestration-preferences.json, use providers.audit, do not hardcode Claude or Codex. Do not poll a running agent indefinitely; if the reviewer has been started but the result has not returned, stop at the review gate, record pending/blocked, and wait for notification or the user's decision.
  2. Otherwise, has the current host's native Codex/Claude Task/Agent tool: use a native Task agent for independent-context review. If it is a same-type agent, record the degradation and residual risk in the report.
  3. Neither is available: local review can only be finalized after recording local-only and obtaining the necessary authorization; without authorization, report blocked, do not pretend to have started one.

The independent Task agent reviewer prompt must provide only the raw materials and boundaries, and must not reveal local review conclusions:

你是 CodeStable feature design 的独立方案审查 agent。只读，不修改文件，不更新 design/checklist。

请读取：
- .codestable/attention.md
- {design_path}
- {checklist_path}
- 同目录 intent / brainstorm（如有）
- 相关 roadmap / requirement / architecture / compound 文档
- design 引用到的关键代码、接口、类型、组件、命令入口

按 cs-feat-design-review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。
重点审查：需求边界、术语冲突、名词层现状→变化、module interface depth / seam / adapter、编排层流程、挂载点可卸载性、结构健康度、验收契约、steps 原子性、checks 来源、基线与验证命令、交付物、清洁度、roadmap 接口契约遵守情况。
每条 finding 必须有 design/checklist/doc/code 事实证据、影响、建议修复边界。
不要写 {slug}-design-review.md；只把审查结果回传给主 agent。

The main agent remains the party ultimately responsible for review: it must verify each finding of the independent Task agent reviewer item by item, deduplicate, assign severity, and merge into {slug}-design-review.md. External conclusions that have not undergone local fact verification can only be written as residual-risk or ignored, and cannot be directly escalated to blocking。

Review process

1. Scope and facts

  • Use sections 0/1 of the design to confirm terminology, requirements summary, explicit non-goals, complexity tier, and key decisions.
  • Use sections 2.1 / 2.2 to confirm whether both the noun layer and the orchestration layer have "current state → change", and that the current state points to real code / documentation.
  • Use section 2.3 to confirm whether the mounting point is tightened according to "does it disappear if the feature is deleted".
  • Use section 2.4 and the checklist steps to align the rollout strategy, exit signals, and verification actions.
  • Use section 2.5 to confirm that the structural health assessment covers file level + directory level, and that micro-refactoring only does "move only, do not change behavior".
  • Use sections 3/4 to confirm the acceptance contract, architecture write-back predictions, and evidence types.
  • When starting from the roadmap, additionally verify that the interface contract in section 4 of the roadmap is a hard constraint, and that the design has not bypassed it on its own.

2. Independent Review Merge

  • Record the main agent's self-check result:paseo / native-agent / local-only。
  • When no independent Task agent reviewer has been started, record that there is genuinely no capability / the provider is unavailable / the user authorized degradation; if these conditions are not met, do not finalize. passed。
  • After starting a Paseo subagent / native Task agent, the final verdict must wait for the reviewer to return.
  • After the reviewer returns, perform local fact verification item by item; only merge when it can be supported by design / checklist / documentation / code evidence.
  • When the reviewer fails, is blocked by permissions, times out, or is still running, do not silently degrade; report status: blocked。

3. Design Review

Cover at least:

  • Requirement boundaries: whether the user goals, core behavior, success criteria, and explicit non-goals are verifiable.
  • Terminology and current state: whether key terms conflict with code / architecture / historical features; whether the current-state description is true.
  • Noun layer: whether value objects, entities, interfaces, types, and component props/events clearly describe the changes.
  • Module/interface design: whether the interface includes the invariant / ordering / error mode that the caller must know; whether the module is deep; whether the seam / adapter is genuinely needed; whether tests can observe behavior through the interface.
  • Orchestration layer: whether the main flow diagram, branches, error semantics, idempotency, concurrency, and observability points can run through.
  • Mount points: whether real external registration points are listed, rather than a list of internally changed files.
  • Structural health: whether micro-refactoring is necessary and its boundaries are safe; whether directory convention candidates are reasonable.
  • Acceptance contract: whether normal / boundary / error paths are covered, and whether there is an evidence type.
  • checklist: whether steps are independently verifiable, whether exit_signal is yes/no, and whether all checks can be traced back to the design.
  • Baseline and validation: whether required commands, pre-check strategy, and baseline red-light attribution are clearly written.
  • Deliverables and cleanliness: whether acceptance can be verified from repository facts; whether rules for debug output, TODO, dead imports, etc. are explicit.

4. Feature Design Review Invariants and Evidence Grading

Each review round must produce an Evidence Confidence Ledger. Evidence grading only describes the source of the basis, not a quality score:

  • E Embedded: directly visible in design / checklist / roadmap item / command output.
  • C Context: supported by relevant req / arch / compound / code facts.
  • H Heuristic: engineering experience or reviewer judgment, lacking direct repository evidence.

Core invariants:

  • The Acceptance Coverage Matrix covers every core acceptance scenario.
  • Every core scenario can be traced to a checklist step, evidence type, and command / action.
  • checklist steps are independently verifiable, and checks can be traced back to the design source.
  • A design originating from the roadmap does not bypass the roadmap interface contract.
  • The DoD Contract covers Design / Implementation / Review / QA / Acceptance DoD, Validation Commands, and Required Artifacts.
  • Module/interface design covers depth, seam placement, and dependency strategy; when no interface is added / changed, it can be marked not-applicable.
  • checklist dod.commands If present, the field uses {id, command, core, failure_handling}; the design table is only a human-readable projection.
  • If a core check has only H evidence, it cannot be silently passed; at minimum write it into residual risk, and when necessary list it as an important / blocking finding.

Severity

  • blocking: Must be fixed first. It would prevent the design from being effectively reviewed by the user, result in no stable contract for implementation, allow the roadmap contract to be bypassed, make steps/checks impossible to execute, make acceptance non-falsifiable, and leave key risks without a verification path.
  • important: Should be fixed; if the user decides to defer it, it must be explicitly recorded in the design review and the user review summary.
  • nit: Minor clarity or consistency suggestion, non-blocking.
  • suggestion: Alternative design approaches or reinforcement suggestions, not required to be adopted this time.
  • learning: Informational note, no action required.
  • praise: Records design practices worth keeping; a small number is enough.
  • residual-risk: Uncertainty that review cannot fully eliminate and that requires focused re-verification in user review, implementation, code review, QA, or acceptance.

Do not escalate a personally preferred implementation style into blocking. Blocking must be supportable by the design contract, checklist, roadmap/req/arch, code facts, or reliable engineering principles.

Report Template

Report path:.codestable/features/{feature}/{slug}-design-review.md。

---
doc_type: feature-design-review
feature: {feature}
status: passed|changes-requested|blocked
reviewed: YYYY-MM-DD
round: 1
---

# {slug} feature design 审查报告

## 1. Scope And Inputs

- Design: {path}
- Checklist: {path}
- Intent / brainstorm: {path / none}
- Roadmap: {path / none}
- Related docs: {requirements / architecture / compound}
- Code facts checked: {paths / none}

### Independent Review

- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked
- Detection: paseo|native-agent|local-only|skipped
- Provider / agent: {providers.audit / agent id / none}
- Raw output: {摘要 / 路径 / none}
- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿}
- Gate effect: {none | blocks final verdict until completed / user-approved downgrade}

## 2. Design Summary

- Goal: {摘要}
- Key contracts: {名词层 / 编排层摘要}
- Steps: {数量 + 风险热点}
- Checks: {数量 + 来源完整性}
- Baseline / validation: {摘要}

## 3. Findings

### blocking

- [ ] FDR-001 `{path#section|checklist.step|file:line}` {问题}
  - Evidence: {事实}
  - Impact: {为什么阻塞用户 review / implement}
  - Expected fix scope: {修复边界}

### important

- [ ] FDR-00N `{证据位置}` {问题}
  - Evidence: {事实}
  - Impact: {影响}

### nit

- [ ] FDR-00N `{证据位置}` {建议}

### suggestion

- [ ] FDR-00N {建议}

### learning

- {可复用设计经验或注意点}

### praise

- {值得保留的做法}

## 4. User Review Focus

- 用户需要重点拍板：{决策 / 假设 / 不做范围}
- implement 需要重点遵守：{契约 / steps / 验证}
- code review / QA / acceptance 需要重点复核：{风险 / 证据}

## 5. Evidence Confidence Ledger

| Check | Verdict | Evidence Class | Basis | Follow-up |
|---|---|---|---|---|
| Acceptance Coverage Matrix | pass|warn|fail | E|C|H | {路径 / 事实 / 判断依据} | {none / 复核点} |
| DoD Contract | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Steps and checks traceability | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Roadmap contract compliance | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Module interface design | pass|warn|fail|n/a | E|C|H | {依据} | {复核点} |
| Validation and artifacts | pass|warn|fail | E|C|H | {依据} | {复核点} |

Summary: E={n}, C={n}, H={n}, H-only core checks={列表或 none}。

## 6. Residual Risk

- {风险 + 下游如何处理；没有写 none}

## 7. Verdict

- Status: passed|changes-requested|blocked
- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等独立 Task agent reviewer 完成 / 用户确认降级后重跑

When there is no finding of a certain type, write none, do not delete the section; the next review round must be able to compare.

Exit Conditions

  • attention, design, checklist, and relevant intent / brainstorm / roadmap / req / arch / compound have been read.
  • Necessary code, interface, type, component, or command facts have been verified as declared by the design.
  • The checklist has been confirmed parseable, and all steps/checks are traceable.
  • An independent reviewer has been started per the Task agent selection rules; if not started, it has been recorded that there is truly no capability / the provider is unavailable / the user authorized degradation.
  • If an independent Task agent reviewer was started, it has been waited on until completed and the findings have been merged / rejected one by one with local verification; otherwise, the report status: blocked, and did not enter user review.
  • Requirement boundaries, terminology, noun layer, orchestration layer, mount points, structural health, acceptance contract, steps/checks, baseline, deliverables, and cleanliness have been reviewed.
  • The Acceptance Coverage Matrix, Feature Design Review Invariants, and Evidence Confidence Ledger have been checked.
  • Core checks were not silently passed when H-only.
  • Written .codestable/features/{feature}/{slug}-design-review.md。
  • When there is blocking / unhandled important, it points to cs-feat-design revise and rerun review.
  • When there is no blocking and important items are handled or explicitly accepted, explicitly tell the user that the next step is manual feature design review.

Common Pitfalls

  • Turning design review into copy polishing without reviewing whether steps/checks are executable.
  • Only reading the design without checking the checklist sources.
  • Not checking interface contracts at the start of the roadmap, causing features to secretly bypass the roadmap.
  • Letting the current-state section pass without reading the code, only to discover during implementation that the design does not hold up.
  • Steps contain "and / as well as / at the same time" but are not rechecked to see whether they should be split.
  • Treating batch design or being short on time as a reason for local-only degradation.
  • Finalizing the local review as passed before the results come back after starting an independent Task agent reviewer.
  • Copying the external reviewer's conclusions without local fact verification.
  • The review report is not saved to disk, leaving user review and subsequent implementation without traceable input.