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

cs-roadmap-review

General & other

View repository

Updated 10-15 20:30

About this skill

cs-roadmap-review

Required reading at startup

Before making any judgment or taking any action, first run the CodeStable preflight: read .codestable/attention.md; if missing, first cs-onboard; do not read an external AI entry point as a substitute (see .codestable/reference/execution-conventions.md）。

This stage is the planning review gate before the roadmap is handed to the user for manual confirmation. It only reads the roadmap, items, related documents, and necessary code facts, and only writes {slug}-roadmap-review.md, does not directly modify the roadmap, does not approve the roadmap on the user's behalf, and does not advance feature design.

The goal is not to pursue "the plan looks complete," but to confirm that this roadmap already has the conditions for the user to review effectively: goals are falsifiable, scope boundaries are clear, module breakdown and interface contracts are executable, sub-features can be independently verified, the dependency DAG is reasonable, and risks and verification strategies are exposed in advance.

For shared paths and naming conventions see .codestable/reference/shared-conventions.md. The specific structure of the roadmap is based on the target {slug}-roadmap.md / {slug}-items.yaml and the project's shared conventions. Report language: the body of the roadmap-review report must follow .codestable/attention.md usingChinese; if the draft uses English, rewrite it into Chinese before writing to disk. frontmatter / yaml fields are not translated.

Input

Before entering review, you must read:

  • .codestable/attention.md
  • .codestable/roadmap/{slug}/{slug}-roadmap.md
  • .codestable/roadmap/{slug}/{slug}-items.yaml
  • Relevant drafts/ materials in the roadmap directory (read-only, only those directly related to this candidate)
  • requirement / architecture documents pointed to by the roadmap frontmatter
  • Related documents mentioned in the observation items in section 7 of the roadmap
  • Related compound deposits: use the project search tool to search for decision / learning / explore / trick by major requirement keywords
  • Existing in items.yaml with feature field's feature design / acceptance (in update mode or during re-review)
  • Key code locations referenced by interface contracts or module breakdown in the roadmap
  • Independent Task agent reviewer output (if already started this round)

When there are no code references, do not force a full-repository scan; but when the roadmap claims reuse of existing modules, interfaces, commands, configurations, or data structures, you must read the corresponding code or document facts to verify.

Startup check

  1. The roadmap main document exists, frontmatter doc_type=roadmap，slug matches the directory,status is one of draft|active|paused|completed .
  2. items.yaml exists,roadmap matches the slug,items is non-empty.
  3. Each item in items.yaml has slug / description / depends_on / status / feature / minimal_loop。
  4. The dependency graph can be resolved; when there are cycles, self-references, or unknown dependencies, list them directly as blocking.
  5. If there is already {slug}-roadmap-review.md：
    • status: passed and roadmap/items have not changed: indicate that the user review can proceed.
    • status: changes-requested / blocked: read the old findings and confirm whether to re-review.
    • roadmap/items 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 consolidation 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 after seeing the degradation risk, is local-only / skipped-by-userallowed. Batch roadmaps, being in a hurry, or the main agent considering the risk low are not reasons for degradation; when authorization for degradation is needed, first follow .codestable/reference/approval-conventions.md and write approval-report.md, then let the user choose.

Once an independent Task agent reviewer should be or has been started for this round, it is the input to this round's review gate. The main agent may first produce a local review draft, but must not finalize before the reviewer returns {slug}-roadmap-review.md, must not give passed, and must not hand the roadmap 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 keep waiting, retry the reviewer, or explicitly downgrade to a local-only review.

Detection is done by the main agent self-checking its own tools at runtime, not by guessing the environment with scripts—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 a Paseo subagent; otherwise the current host's native Codex/Claude Task/Agent):

  1. Has the mcp__paseo__create_agent tool: must prefer using a Paseo subagent for read-only independent review (first choice: able to switch providers, achieving truly heterogeneous review). Before starting, first load/read the current instructions 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, if the current host's native Codex/Claude Task/Agent tool is available: use a native Task agent for independent-context review. If it is the same type of agent, record the downgrade and residual risk in the report.
  3. If neither is available: local review can only be finalized after recording local-only and obtaining the necessary authorization; without authorization, report blocked, and do not pretend to have started one.

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

你是 CodeStable roadmap 的独立规划审查 agent。只读，不修改文件，不更新 roadmap/items。

请读取：
- .codestable/attention.md
- {roadmap_path}
- {items_path}
- roadmap frontmatter 指向的 requirement / architecture 文档
- roadmap 相关 compound / draft 材料
- roadmap 引用到的关键代码或命令入口

按 cs-roadmap-review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。
重点审查：目标完成信号、范围与明确不做、模块拆分、interface depth / seam placement / adapter、接口契约可执行性、子 feature 原子性、依赖 DAG、最小闭环、验证策略、风险缓解、知识回写点、用户是否能据此有效拍板。
每条 finding 必须有 roadmap/items/doc/code 事实证据、影响、建议修复边界。
不要写 {slug}-roadmap-review.md；只把审查结果回传给主 agent。

The main agent remains the party ultimately responsible for the review: it must verify each finding of the independent Task agent reviewer one by one, deduplicate, rank, and merge them into {slug}-roadmap-review.md. External conclusions that have not been verified against local facts can only be written as residual-risk or ignored, and cannot be directly escalated to blocking。

Review process

1. Scope and facts

  • Use roadmap sections 1/2 to confirm the goal, coverage scope, explicit non-goals, and key assumptions.
  • Use sections 3/4 to confirm whether the module breakdown and interface contracts are sufficient to support sharing across multiple features.
  • Use section 5 and items.yaml to align all sub-features: slug, description, owning module, dependencies, status, feature binding, minimal_loop.
  • Use the relevant req / arch / compound to determine whether there are conflicts, duplicate planning, or missing constraints.
  • Use code facts to verify the roadmap's description of existing modules, commands, interfaces, configuration, and data structures.

2. Independent review merge

  • Record the main agent's self-check results:paseo / native-agent / local-only。
  • If no independent Task agent reviewer was started, record that there truly was no capability / the provider was unavailable / the user authorized a downgrade; 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; merge only what can be supported by documentation / code / items evidence.
  • If the reviewer fails, is blocked by permissions, times out, or is still running, do not silently downgrade; report status: blocked。

3. Planning review

At minimum cover:

  • Goal completion signal: whether completion / non-completion can be observed, accepted, and determined.
  • Scope and explicit non-goals: whether they are concrete, and whether they can prevent later features from quietly expanding scope.
  • Module breakdown: whether responsibilities are clear, and whether there are duplicate modules, catch-all modules, or missing modules.
  • Module/interface design: whether it creates pass-through modules; whether cross-module interfaces are deep; whether seams / adapters are genuinely needed; whether the dependency strategy supports subsequent testing.
  • Interface contracts: whether they are written down to the level of function signatures / data structures / protocol fields / error codes; whether it is explicitly stated when there is no cross-module interface.
  • Sub-feature atomicity: whether each one can be independently designed / implemented / reviewed / QA'd / accepted; whether the description is falsifiable.
  • Dependency DAG: whether it is acyclic, whether the dependency rationale is concrete, and whether the weakest dependency is verified first.
  • Minimal closed loop: whether an end-to-end demo is possible after the first item or the minimal path is completed.
  • Verification and baseline: whether build / typecheck / lint / test / e2e / manual verification entry points are identified; whether a safety net is arranged when the baseline is unstable.
  • Risk and recovery: whether top risks, external dependencies, migration / permissions / security / rollback are exposed in advance.
  • Deliverables and knowledge write-back: whether subsequent acceptance can verify artifacts from repository facts; whether stable conventions / pitfalls have candidates for documentation.

4. Roadmap 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 roadmap / items.yaml / checklist / 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 Granularity Gate can explain why it enters the roadmap, rather than a single feature / brainstorm.
  • Every core completion signal in the Goal Coverage Matrix has an item, a verification entry point, and an evidence type.
  • items.yaml is still a DAG, and the minimal closed loop can be independently accepted.
  • Interface contracts can be used as hard constraints by feature-design.
  • Cross-module interfaces have a basis in depth / seam / dependency strategy; when there is no cross-module interface, explicitly state not-applicable.
  • If a core check has only H evidence, it cannot be silently passed; at minimum record it in residual risk, and when necessary list it as an important / blocking finding.

Severity

  • blocking: must be fixed first. It would cause users to be unable to effectively review, features to be unable to execute independently, interface contracts to be unusable, dependency cycles, clear violations of req / arch, key risks not covered, or acceptance not falsifiable.
  • important: should be fixed; if the user decides to defer, it must be explicitly recorded in the roadmap review and the user review summary.
  • nit: minor clarity or consistency suggestion, non-blocking.
  • suggestion: alternative breakdown or reinforcement idea, not required to be adopted this time.
  • learning: informational explanation, no action required.
  • praise: record planning practices worth keeping; a small number is enough.
  • residual-risk: uncertainty that review cannot fully eliminate and that needs user review or focused re-check in subsequent feature-design.

Do not escalate a personally preferred decomposition method into blocking. blocking must be supportable by roadmap contracts, items facts, relevant documents, code facts, or reliable engineering principles.

Report Template

Report path:.codestable/roadmap/{slug}/{slug}-roadmap-review.md。

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

# {slug} roadmap 审查报告

## 1. Scope And Inputs

- Roadmap: {path}
- Items: {path}
- Related docs: {requirements / architecture / compound / drafts}
- 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. Roadmap Summary

- Goal completion signal: {摘要}
- Module split: {摘要}
- Interface contracts: {摘要}
- Items: {数量 + minimal loop + 风险热点}
- Dependency shape: {DAG / 问题}

## 3. Findings

### blocking

- [ ] RMR-001 `{path#section|items.slug|file:line}` {问题}
  - Evidence: {事实}
  - Impact: {为什么阻塞用户 review / 后续 feature}
  - Expected fix scope: {修复边界}

### important

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

### nit

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

### suggestion

- [ ] RMR-00N {建议}

### learning

- {可复用规划经验或注意点}

### praise

- {值得保留的做法}

## 4. User Review Focus

- 用户需要重点拍板：{决策 / 假设 / 优先级}
- 后续 feature-design 需要重点复核：{接口 / 风险 / 验证}
- 不能靠 roadmap review 完全确认的点：{列表}

## 5. Evidence Confidence Ledger

| Check | Verdict | Evidence Class | Basis | Follow-up |
|---|---|---|---|---|
| Granularity Gate | pass|warn|fail | E|C|H | {路径 / 事实 / 判断依据} | {none / 复核点} |
| Goal Coverage Matrix | pass|warn|fail | E|C|H | {依据} | {复核点} |
| DAG and minimal loop | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Interface contract usability | pass|warn|fail | E|C|H | {依据} | {复核点} |
| Module interface depth | pass|warn|fail|n/a | E|C|H | {依据} | {复核点} |

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

## 6. Residual Risk

- {风险 + 用户 review / feature-design 如何处理；没有写 none}

## 7. Verdict

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

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

Exit Conditions

  • Have read attention, roadmap, items, and relevant req / arch / compound / drafts.
  • Have verified the necessary code or command facts as declared by the roadmap.
  • Have confirmed that items.yaml is parseable and the dependency graph has no unknown nodes; any issues have been listed as findings.
  • Have launched an independent reviewer according to the Task agent selection rules; if not launched, have recorded that there was truly no capability / provider unavailable / user-authorized downgrade.
  • If an independent Task agent reviewer was launched, have waited until completed and locally verified each finding for merge / rejection; otherwise report status: blocked, and did not enter user review.
  • Have reviewed goals, scope, modules, interfaces, feature atomicity, dependencies, minimum closed loop, verification, risks, and knowledge write-back.
  • Have checked the Granularity Gate, Goal Coverage Matrix, and Roadmap Review Invariants.
  • Have written the Evidence Confidence Ledger; did not silently pass when core checks were H-only.
  • Have written .codestable/roadmap/{slug}/{slug}-roadmap-review.md。
  • When there is blocking / unhandled important, point to cs-roadmap to revise and rerun review.
  • When there is no blocking and important items have been handled or explicitly accepted, clearly tell the user that the next step is manual roadmap review.

Common Pitfalls

  • Treating roadmap review as grammar checking, without reviewing interface contracts and the dependency graph.
  • Only reading the main document, without checking items.yaml.
  • Not reading requirement / architecture, causing conflicts between planning and the current state to go undetected.
  • Letting interface contracts that say "TBD" pass, so each subsequent feature invents its own interface.
  • Stuffing multiple independently acceptable deliverables into a sub-feature but treating it as only one.
  • Using batch roadmap work or being pressed for time as a reason for local-only downgrade.
  • After launching an independent Task agent reviewer, finalizing the local review as passed before the result comes back.
  • Copying the external reviewer's conclusions without local fact verification.
  • The review report is not written to disk, causing user review and subsequent design to have no traceable input.