easysdd-architecture-check

Applicable Scenarios

• Verify internal consistency of a design before it enters implementation
• Confirm alignment between code and design when a feature is nearing acceptance
• Ensure new content does not conflict with old agreements after revising a design

• Users want direct fixes → redirect to

  easysdd-feature-implement

  or

  easysdd-issue-fix

• Users want to make decision-making calls → redirect to

  easysdd-decisions

• Users do not have a design → first redirect to

  easysdd-feature-design

Single-Target Rule

• design-internal

  : Internal consistency of the design

• design-vs-code

  : Consistency between design and code

See

easysdd/reference/shared-conventions.md

for shared paths and naming conventions.

Workflow

Phase 1: Lock the Check Target

• Current check target (

  design-internal

  /

  design-vs-code

  )
• Which single feature to check
• Check scope (which section, which module)

Phase 2: Read Materials

• AGENTS.md

• Full text of the design document
• Relevant documents in the architecture center directory (e.g., DESIGN.md)

design-vs-code

• Code files directly corresponding to Sections 2/3 of the design

Phase 3: Execute Check

Target A: design-internal

1. Terminology consistency — whether terms defined in Section 0 are replaced with synonyms or have semantic drift in later sections
2. Requirement alignment — whether the summary in Section 1 is consistent and does not deviate from confirmed goals
3. Contract closure — whether contract examples in Section 2 have corresponding modification plans in Section 3
4. Consistency between examples and decisions — whether the behavior of contract examples in Section 2 conflicts with key decisions in Section 1
5. Scope guard — whether modification plans in Section 3 exceed the "explicitly not to be done" items in Section 1
6. Implementation executability — whether implementation steps in Section 3 are verifiable and have no conflicting dependencies

Target B: design-vs-code

1. Type consistency — whether core types/fields defined in Section 2 of the design exist in the code and have consistent semantics
2. Behavior consistency — whether the input→output stated in Section 2 of the design matches the actual code behavior
3. Write path consistency — whether the write entry stated in the design has any additional bypass writes in the code
4. Boundary behavior consistency — whether exception/boundary rules in Section 1 of the design are implemented in the code
5. Modification boundary consistency — whether the modification scope stated in Section 3 of the design is not exceeded or missing in the code
6. Implementation result consistency — whether the exit signals for each step in Section 3 of the design are verifiable in the corresponding code state

Phase 4: Output Check Report

# Architecture Consistency Check Report

> Target: design-internal | design-vs-code
> Scope: {feature}/{module}/{section scope}
> Date: YYYY-MM-DD
> Conclusion: pass | pass-with-risk | fail

## 1. Check Summary

One-sentence summary.

## 2. Inconsistency List

| ID | Severity | Location | Phenomenon | Impact | Suggested Fix |
|---|---|---|---|---|---|
| AC-01 | High/Medium/Low | `{file}:{line number}` or `Design Section X` | Description | Consequence | Repair suggestion (not to be executed) |

## 3. Observation Items (Out of Scope, No Modifications)

If the following structural issues are found when reading `easysdd/architecture/`, list them here and let the user decide whether to initiate another workflow to handle them:

- A certain type has ≥6 files in the root directory and is still placed flat (violates the same-type aggregation rule in `easysdd/reference/shared-conventions.md`, should trigger `easysdd-architecture-gen` for relocation)
- File names do not follow `{type}-{slug}.md`, making future aggregation impossible
- Other unreasonable points observed incidentally that are unrelated to the current check target

Omit this section if none.

## 4. Well-Consistent Items

List 2-5 key points that passed the check — a report with only negative information will cause users to lose confidence in the overall system.

## 5. Suggested Next Steps

- fail: Suggest which items to fix first before re-running this skill
- pass-with-risk: Key points to focus on regression during implementation/acceptance
- pass: Proceed to the next phase

• High: Will lead to incorrect implementation directions, or code has substantially deviated from the design (missing key contract implementations, opposite behavior, different references for terms)
• Medium: Intent can be guessed but ambiguity remains, prone to misinterpretation downstream (synonym drift, contract examples and decisions seem aligned but have detail conflicts, unclear exit signals)
• Low: Awkward expression or readability issues, no impact on understanding (poor order, wording can be optimized)

Hard Boundaries

1. Check only, no fixes — modifying design/code/configuration is prohibited
2. Single target — only

   design-internal

   or

   design-vs-code

   per check
3. Evidence-based — each inconsistency must have a locatable position (file:line number or design section)
4. Executable suggestions — specific to "what to change and how to change", but not implemented
5. No divergence — out-of-scope issues are only recorded as "observation items" and not explored in depth

Exit Conditions

• Single check target has been locked
• Check items corresponding to the target have been fully covered
• Report includes inconsistency list + repair suggestions
• Report does not contain any actual repair actions
• User has confirmed the conclusion of this round of checks

Common Pitfalls

• ❌ Conducting

  design-internal

  and

  design-vs-code

  checks at the same time
• ❌ Modifying code or documents immediately when issues are found
• ❌ Only saying "something is wrong here" without providing evidence location
• ❌ Giving overly abstract suggestions (e.g., "optimize the architecture")
• ❌ Expanding infinitely from one target to full repository audit