AgentSkillsCN

review-plan

方案评审与咨询——在正式实施前，全面验证方案的准确性与完整性，及时发现并弥补潜在漏洞。适用于任何包含调研与规划环节的任务。

SKILL.md
--- frontmatter
name: review-plan
description: Advisory plan review - validates plan correctness and identifies gaps before implementation. Works on any task with research and plan sections.
argument-hint: [task-identifier]
<skill name="apex:review-plan" phase="advisory"> <overview> Lightweight plan review that catches gaps and errors before implementation commitment.

Three focused lenses:

  1. •Completeness - Are all required plan artifacts present and substantive?
  2. •Gap Analysis - What did research find that plan doesn't address?
  3. •Correctness - Is the plan internally consistent and feasible?

Output goes to chat. User fixes issues inline, then proceeds to implement. </overview>

<phase-gate requires="none" sets="none"> <reads-file>./.apex/tasks/[ID].md</reads-file> <expects-sections>research, plan</expects-sections> <outputs-to>chat</outputs-to> </phase-gate> <principles> - **Advisory Only**: No phase changes, no file modifications - **Fast**: Direct analysis, no subagents - **Actionable**: Every gap or error includes what to fix - **Honest**: Call out real problems, don't rubber-stamp - **Flexible**: Works regardless of current phase </principles> <initial-response> <if-no-arguments> I'll review the plan for gaps and correctness. Please provide the task identifier.

You can find tasks in ./.apex/tasks/ or run with: /apex:review-plan [identifier] </if-no-arguments> <if-arguments>Load task file and begin review.</if-arguments> </initial-response>

<workflow> <step id="1" title="Load task and extract sections"> <instructions> 1. Read `./.apex/tasks/[identifier].md` 2. Note current phase from frontmatter (informational only - don't block) 3. Extract and parse (note any missing sections): - `<task-contract>` - From within `<research>` section - `<research>` - All findings from research phase - `<plan>` - All artifacts from plan phase 4. If `<research>` or `<plan>` sections are missing/empty, report as finding (don't refuse) 5. Verify file paths mentioned in `<plan><architecture-decision><files-to-modify>` exist using glob/ls </instructions> </step> <step id="2" title="Completeness Check"> <purpose> Verify all mandatory plan artifacts are present and substantive. </purpose> <mandatory-artifacts> Look for these concepts (tag names may vary):
  1. •Design Rationale - Current state, problem breakdown, hidden complexity, success criteria
  2. •Tree of Thought - 3 different solution approaches with a winner selected
  3. •Chain of Draft - Evolution through multiple drafts
  4. •YAGNI - What's explicitly excluded, complexity budget
  5. •Patterns - Which patterns are being applied (can be empty)
  6. •Architecture Decision - Files to change, implementation steps, how to validate
  7. •Builder Handoff - Clear mission, ordered steps, validation checkpoints
  8. •Contract Validation - AC coverage confirmation </mandatory-artifacts>
<contract-validation> - [ ] Plan acknowledges the current contract version - [ ] If amendments exist in task-contract, they are acknowledged in plan - [ ] Every AC in task-contract is addressed somewhere in plan </contract-validation> <output-format> ## Completeness Check

Missing Artifacts

  • •[Artifact name]: Not found or empty
    • •Fix: Add required section to plan

Incomplete Artifacts

  • •[Artifact name]: Missing [specific subsection]
    • •Fix: Add [subsection] with [expected content]

Contract Issues

  • •Version mismatch: Contract v[X] but plan references v[Y]
    • •Fix: Update plan to reference current contract version
  • •Unacknowledged amendment: Amendment not recorded in plan
    • •Fix: Acknowledge the amendment in plan

Completeness Score: [N] artifacts present, [N] issues </output-format> </step>

<step id="3" title="Gap Analysis"> <purpose> Find what research discovered that plan doesn't address. </purpose> <checklist> **Research Risks vs Plan Mitigations:** - [ ] Every risk identified in research has a mitigation in plan - [ ] High-probability AND high-impact risks have explicit handling - List any unaddressed risks with their probability/impact

Research Security Concerns vs Plan:

  • • Security concerns from research are addressed in plan OR explicitly excluded
  • •List any unaddressed security concerns

Pattern Provenance:

  • • Patterns claimed in plan can be traced to research (APEX patterns or codebase conventions)
  • • Trust scores roughly match what research found
  • •List any patterns that appear fabricated or unsupported

Documentation Drift:

  • • Docs flagged for update in research are included in plan's files to modify (or noted as intentionally skipped)
  • •List any documentation that will drift

Research Recommendations vs Chosen Solution:

  • • Plan's chosen solution aligns with research recommendation (or has justification for divergence)
  • •List any unexplained divergences

Task Contract Coverage:

  • • Every AC in task-contract maps to implementation steps
  • • Non-functional requirements are addressed in validation approach
  • •List any uncovered ACs or NFRs

Complexity Budget:

  • • Plan's complexity estimate is reasonable given what research found
  • •Flag if plan seems significantly over/under-scoped </checklist>
<output-format> ## Gap Analysis

Unaddressed Risks

  • •[Risk name] (probability: [H/M/L], impact: [H/M/L]): Research identified [description]. Plan has no mitigation.
    • •Fix: Add mitigation to plan's risk section.

Security Gaps

  • •[Concern]: From research, not addressed in plan.
    • •Fix: Add to risks or explicitly exclude with rationale.

Pattern Issues

  • •[Pattern]: Claimed in plan but can't find source in research.
    • •Fix: Remove pattern or trace back to research source.
  • •[Pattern]: Trust score mismatch ([X] in plan vs [Y] in research).
    • •Fix: Align trust score with research.

Documentation That Will Drift

  • •[doc path]: Research flagged for update, not in plan's files to modify.
    • •Fix: Add to files or note why update not needed.

Uncovered Requirements

  • •AC-[N]: [Description] - No implementation step addresses this.
    • •Fix: Add step to cover this AC.
  • •NFR [type]: [Constraint] - Not validated.
    • •Fix: Add validation for this constraint.

Gap Score: [N] gaps ([N] critical, [N] moderate, [N] minor) </output-format> </step>

<step id="4" title="Correctness Check"> <purpose> Verify plan is internally consistent and feasible. </purpose> <checklist> **Internal Consistency:** - [ ] Chosen solution in summary/metadata matches the winner in Tree of Thought - [ ] Complexity estimate aligns with risks (high risk → expect higher complexity) - [ ] Implementation sequence in architecture decision matches builder handoff - [ ] Risk level matches actual risks identified - List any contradictions

Tree of Thought Validity:

  • • 3 solutions are genuinely different approaches (not variations of same idea)
  • • Winner selection has concrete reasoning citing evidence (not "this feels right")
  • • Pros/cons reference specific findings from research, not hypotheticals

Chain of Draft Evolution:

  • • Final draft is meaningfully different from first draft (not cosmetic rewording)
  • • Issues identified in earlier drafts are resolved in later drafts
  • • Evolution shows actual refinement based on research insights

YAGNI Coherence:

  • • Excluded features don't contradict task contract in-scope items
  • • Excluded features aren't required by any AC

Implementation Sequence:

  • • Steps are in dependency order (foundations before dependents)
  • • Each step has a concrete validation (command to run, not "verify it works")
  • • File paths to modify exist (verify via glob)
  • • New files are clearly marked as new

Validation Quality:

  • • Automated validation includes actual runnable commands (npm test, pytest, etc.)
  • • Manual verification has specific steps, not vague checks

Feasibility:

  • • No circular dependencies in implementation sequence
  • • Patterns applied at sensible locations (not generic "apply everywhere")
  • • No magical thinking ("this edge case won't happen") </checklist>
<output-format> ## Correctness Check

Internal Contradictions

  • •[Field A] vs [Field B]: [A] says [X] but [B] says [Y]
    • •Fix: Reconcile to [recommendation]

Tree of Thought Issues

  • •Solutions not distinct: [A] and [B] are variations of same approach
    • •Fix: Replace [B] with genuinely different architecture
  • •Weak winner reasoning: Selection based on preference, not evidence
    • •Fix: Add specific research findings supporting choice

Implementation Issues

  • •Step [N]: [Problem - missing validation, wrong order, etc.]
    • •Fix: [Specific correction]
  • •Vague validation gate: "[gate text]" is not testable
    • •Fix: Replace with concrete command: [suggested command]

File Path Issues

  • •[path]: Listed in files-to-modify but does not exist
    • •Fix: Correct path or move to files-to-create

Feasibility Concerns

  • •[Concern]: [Why this might not work]
    • •Fix: [How to address]

Correctness Score: [SOUND / MINOR_ISSUES / MAJOR_ISSUES] </output-format> </step>

<step id="5" title="Deliver Review"> <output-format> # Plan Review: [Task Title]

Summary

DimensionStatusIssues
Completeness[✅ Complete / ⚠️ Gaps / ❌ Missing Artifacts][N]
Gap Analysis[✅ Clean / ⚠️ Gaps / ❌ Major Gaps][N]
Correctness[✅ Sound / ⚠️ Minor Issues / ❌ Major Issues][N]

Recommendation: [PROCEED / REVISE / RETHINK]

Completeness Check

[From step 2]

Gap Analysis

[From step 3]

Correctness Check

[From step 4]

Action Items

Must Fix Before Implement

Issues that will cause implementation to fail or produce wrong results

  1. •[Issue with specific fix]

Should Address

Issues that won't block but will cause problems later

  1. •[Issue with specific fix]

Consider

Improvements that would make the plan better

  1. •[Suggestion]

Next Steps

[If PROCEED]: Ready for /apex:implement [identifier] [If REVISE]: Fix the issues above in this session, then re-run /apex:review-plan [identifier] [If RETHINK]: Fundamental issues found - consider returning to /apex:plan [identifier] to rework architecture </output-format> </step>

</workflow> <classification-rubric> **Must Fix** (blocks implementation): - Missing mandatory artifacts (completeness) - Unaddressed high-impact risks - Fabricated patterns (no source in research) - Uncovered acceptance criteria - File paths that don't exist (listed as modify, not create) - Internal contradictions (metadata vs content) - Vague validation gates with no concrete commands

Should Address (causes problems later):

  • •Unaddressed medium-impact risks
  • •Documentation drift (docs-to-update not in plan)
  • •Unacknowledged contract amendments
  • •Weak Tree of Thought (solutions too similar)
  • •Chain of Draft shows no real evolution
  • •Trust score mismatches
  • •NFRs not validated

Consider (improvements):

  • •Minor inconsistencies in wording
  • •Complexity budget slightly high
  • •Could use additional patterns
  • •Validation could be more thorough </classification-rubric>
<recommendation-criteria> - **PROCEED**: 0 Must Fix items - **REVISE**: 1-3 Must Fix items (fixable in current session) - **RETHINK**: 4+ Must Fix items OR most key artifacts missing OR fundamental architecture problems (wrong solution chosen, contradicts research) </recommendation-criteria> <success-criteria> - Task file read (regardless of phase) - Missing sections reported as findings, not errors - File existence verified via glob/ls - Completeness check: key artifacts assessed - Gap analysis: risks, security, patterns, docs, ACs, NFRs checked - Correctness check: consistency, validity, feasibility assessed - Classification rubric applied consistently - Clear recommendation with actionable next steps </success-criteria> </skill>