architecture-review
Review sprint architecture updates for consistency, quality, and risk
- License 许可
- MIT
- 最近更新
- 2026-09-25
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- architecture-review
- description
- Review sprint architecture updates for consistency, quality, and risk
03 SKILL.md 正文
Architecture Review Skill
Evaluate a sprint's architecture update for consistency with the existing
system, design quality, risks, and completeness. Skippable for
trivial/small sprints -- record the gate result as skipped rather than
running the review.
Process
Where step 2 reads from depends on Project.design_docs_opt_in:
Not opted in (design_docs_opt_in is None or False)
- Read the current architecture in
docs/clasi/architecture/. - Read the sprint's architecture update (the Architecture section of
the sprint's
sprint.md). - Explore the codebase to check alignment between documented and actual architecture.
- Review against the criteria below.
Sprints planned before the single-doc rewrite (sprints 001-017) may still
carry this content in a separate architecture-update.md file in the
sprint directory -- read that file instead for those sprints.
Opted in (design_docs_opt_in is True)
- Read the current canonical docs:
docs/design/design.mdand the subsystem doc(s) named by the sprint's overlay (Project.design_dir). - Read the sprint's overlay diffs: every
<name>.diff.mdfile in the sprint'sclasi/sprints/NNN-slug/design/directory (SUC-007) -- not asprint.mdArchitecture section, which is not used for architecture content when opted in (seearchitecture-authoringMode 2a). A.diff.mdis agent-reviewer input specifically: it shows pristine-vs-edited content as a fenced diff block, generated byclasi.design.overlay.generate_diffs, not authored directly by the sprint-planner. The stakeholder's own review path isgit diffon the sprint'sdesign/directory (e.g. in VS Code) between the seed commit and the pre-execution-approval commit -- reading.diff.mdfiles is this skill's job, not the stakeholder's. - Confirm the overlay validates first. A stale or missing
.diff.mdis aclasi design validate/validate_designfailure (SUC-003) that should have been caught before this review starts -- ifarchitecture-authoring's Step 5 (Validate before handoff) was skipped, run validation now and stop the review with a request to fix it rather than reviewing against a diff that may not reflect the overlay's current content. - Explore the codebase to check alignment between the diffs' claims and actual architecture, same as the not-opted-in path.
- Review against the criteria below -- unchanged; apply the same
five categories to the diffs' content instead of a
sprint.mdsection.
No sprint.md Architecture section exists to read under opt-in for a
compact or substantial sprint -- do not fall back to reading one. For a
trivial sprint under opt-in, there is no overlay and no section either;
record the gate result skipped, same as today.
The five review categories below and the verdict levels are unchanged between the not-opted-in and opted-in paths -- only the input source (step 2 above) differs.
Review Criteria
Version Consistency
- Not opted in: changes in Sprint Changes section reflected in document body? Updated architecture internally consistent? Design rationale updated for changed decisions?
- Opted in: does each
.diff.md's content match what the corresponding overlay file currently contains (i.e. is the diff not stale)? Is the edited overlay document internally consistent? Design rationale updated for changed decisions?
Codebase Alignment
- Does current code match documented architecture?
- If drift exists, does the sprint plan account for it?
- Are proposed changes feasible given actual code state?
Design Quality
- Cohesion: Each component responsible for one concern?
- Coupling: Minimal, intentional, no circular dependencies?
- Boundaries: Clear, enforceable, narrow interfaces?
- Dependency health: No cycles, consistent direction, reasonable fan-out?
Anti-Pattern Detection
- God component, shotgun surgery, feature envy
- Shared mutable state, circular dependencies
- Leaky abstractions, speculative generality
Risks
- Data migration issues, breaking changes
- Performance or security implications
- Deployment sequencing concerns
Verdict
- APPROVE: No significant issues.
- APPROVE WITH CHANGES: Minor issues addressable during implementation.
- REVISE: Significant structural issues that need resolution first.
Guidelines:
- Circular deps, god components, broken interfaces → REVISE
- Single contained anti-pattern → APPROVE WITH CHANGES
- Inconsistencies between Sprint Changes and document body → REVISE
- Missing rationale for significant decisions → APPROVE WITH CHANGES