Design Crystallizer — Claude Code skill for inferring implied design from code context and producing gap analysis

gap-methodology.md

Gap Methodology Reference

Detailed detection techniques for Phase 3 (Gap Analysis) of the Design Crystallizer skill.

Pre-Analysis Setup

Before analyzing individual classes, prepare the measurement context:

1. Record the inferred design statement from Phase 1 — this is the baseline
2. List all classes in scope with their file paths
3. For each class, note its declared identity — name, interfaces, base class
4. Map the class interaction graph within the scope — who calls whom

Per-Class Analysis Protocol

For each class in scope, execute the following in order.

Step 1: Declaration Analysis

Read the class declaration line and immediate structure:

[access] [modifiers] class [Name] : [BaseClass], [Interfaces]

Check against design:

• Does the name match the structural role from the inferred design?
• Does the base class align with the pattern expectation?
• Are the implemented interfaces consistent with the contract obligations?
• Are there interfaces the design implies but the class doesn't implement?
• Are there interfaces the class implements that the design doesn't account for?

Gap signals:

• Name suggests one role, interfaces suggest another → Role Confusion
• Missing interface that siblings implement → Missing Element
• Implements interface no sibling does without clear reason → Excess Element

Step 2: Constructor Analysis

Read all constructors. Examine injected dependencies.

Check against design:

• Do the constructor parameters match the expected dependencies for this structural role?
• Are there dependencies that suggest the class is doing work outside its role?
• Are there missing dependencies that the role would require?
• Multiple constructors — does one bypass required dependencies?

Gap signals:

• Constructor takes a service from a different layer than expected → Structural Deviation
• Constructor takes no dependencies but siblings do → Missing Element or intentional simplicity
• Constructor takes dependencies the role shouldn't need → Role Confusion (may be doing too much)

Step 3: Public Surface Analysis

List all public methods, properties, and events.

Check against design:

• Does the public method set match the expected shape?
• Do method signatures (params, return types) align with contract obligations?
• Are there public methods that should be internal/private?
• Are there methods the contract implies but are missing?

Gap signals:

• Public method that exposes internal mechanics → Structural Deviation
• Missing method that the interface or role implies → Missing Element
• Method that belongs to a different structural role → Role Confusion
• Method no caller uses → Excess Element

Step 4: Private Implementation Analysis

Read private/internal methods and fields.

Check against design:

• Do private methods serve the declared public surface, or reveal hidden responsibilities?
• Is there a private method cluster that should be its own class?
• Do fields hold state appropriate to the structural role?

Gap signals:

• Private method cluster with its own coherent responsibility → Structural Deviation (extract candidate)
• Fields tracking state the role shouldn't own → Role Confusion
• Helper methods duplicating logic from a service that should be injected → Missing Element

Step 5: Control Flow Analysis

Read the behavioral complexity of key methods.

Check against design:

• Does the branching complexity match the role's expected complexity?
• Is a coordinator doing transformation? Is a transformer doing routing?
• Are there error handling patterns inconsistent with siblings?

Gap signals:

• Complex branching in what should be a simple pass-through → Role Confusion
• No error handling where siblings have it → Missing Element
• Error handling strategy diverges from sibling pattern → Structural Deviation

Step 6: Relational Analysis

Map what the class references and what references it.

Check against design:

• Afferent coupling (who depends on this class) — matches expected consumers?
• Efferent coupling (what this class depends on) — matches expected dependencies?
• Any circular references?
• Any dependencies that skip layers?

Gap signals:

• Referenced by classes in unexpected layers → Structural Deviation
• References classes it shouldn't know about → Role Confusion or Structural Deviation
• Not referenced by anything → Excess Element (unless new/planned)

Severity Decision Tree

For each gap found, determine severity:

Is the class's fundamental identity (name + interfaces + role)
contradicted by the finding?
  YES → Critical

Does the finding affect the class's public contract
(what callers see and depend on)?
  YES → High

Does the finding affect internal structure
(how the class does its work)?
  YES → Medium

Is it naming, organization, or style?
  YES → Low

Cross-Class Pattern Analysis

After individual class analysis, look for patterns across the scope:

1. Consistency check: Do all classes of the same structural role follow the same pattern? Divergent classes get flagged.
2. Completeness check: Does the scope have all the structural roles the design implies? Missing roles are gaps.
3. Coupling check: Is the interaction graph between classes consistent with the design's expected topology?

Output Format

Present gaps as a table per class:

### [ClassName] — [Structural Role from Design]

| # | Element | Classification | Severity | Finding | Implication |
|---|---------|---------------|----------|---------|-------------|
| 1 | Constructor | Missing Element | High | No ILogger injected; all siblings have it | Logging gap in error paths |
| 2 | ProcessAsync() | Role Confusion | Medium | Contains routing logic; role is Transformer | Should delegate routing to coordinator |

After all classes, present a scope-level summary:

### Scope Summary

| Classification | Critical | High | Medium | Low | Total |
|---------------|----------|------|--------|-----|-------|
| Role Confusion | 0 | 1 | 2 | 0 | 3 |
| Structural Deviation | 1 | 2 | 3 | 1 | 7 |
| Missing Element | 0 | 3 | 1 | 0 | 4 |
| Excess Element | 0 | 0 | 1 | 2 | 3 |
| **Total** | **1** | **6** | **7** | **3** | **17** |

SKILL.md

name	Design Crystallizer
description	This skill should be used when the user asks to "crystallize design", "infer design", "analyze design structure", "what should this code be", "design extraction", "structural analysis", "code design audit", "design gap analysis", "measure code against design", or mentions inferring implied design from code context, extracting structural intent, or systematically analyzing implementation structure against design expectations.
version	0.1.0

Design Crystallizer

Infer what code should be from its surrounding design context, then measure the implementation against that inference class-by-class, element-by-element. Produce a gap analysis and remediation plan for human approval, then an executable implementation plan.

Core Principle

The implied design comes from the surrounding design context — not from the code being analyzed. The surrounding system tells you what a class should be. The code tells you what it is. The gap between those two is the finding.

• Code is the primary source of truth for what exists
• Surrounding context is the primary source for what should exist
• Documentation is secondary evidence
• Contradictions between code and docs require human resolution — never guess

Pipeline

Execute these 6 phases in strict order. Do not skip phases. Do not combine phases.

Phase 1: Infer

Two sub-phases. Complete both before proceeding.

1a. Context Read

Before examining any code within the scoped area, read the surrounding design environment across 5 axes:

Axis	Question	Where to Look
Layer Position	What layer is this in? What conventions govern this layer?	Project references, namespace hierarchy, CLAUDE.md architecture sections, layer model if available
Upward Contracts	What does the layer above expect from this area?	Interfaces consumed by callers, parameter types passed in, return types expected out
Downward Dependencies	What does this area consume from below?	Constructor parameters, injected services, referenced types from lower layers
Sibling Patterns	What do peer classes in the same layer/namespace look like?	Adjacent files, same directory, same base class family, same interface implementations
Flow Role	What flow(s) pass through here and what role does this area play?	Call chains into and out of the area, orchestrator references, pipeline stage position

Read project-specific context files when available:

• CLAUDE.md architecture sections
• Layer model references (e.g., references/layer-model.md in project skills)
• Code Architecture Schema if present
• Existing specification documents referenced in project docs

These are optional enrichment — the skill functions without them by reading code structure directly.

1b. Design Crystallization

From the 5 axes, synthesize a design statement for the scoped area. Express it as:

• Structural Role: "This area is a [coordinator / transformer / gateway / policy / adapter / ...]"
• Expected Shape: "It should have [N public methods / a single entry point / stateless processing / ...]"
• Contract Obligations: "It must satisfy [interface X / produce type Y / honor invariant Z]"
• Pattern Expectation: "Its siblings follow [pattern], so it should too — or have a documented reason not to"

This statement is the measuring stick for all subsequent phases. It is not aspirational — it is what the surrounding system already implies.

Present the inferred design statement to the user before proceeding.

Phase 2: Reconcile (Human Gate)

Compare code-inferred evidence against documentation evidence:

Outcome	Action
Code and docs agree	Proceed to Phase 3. Note: high confidence.
Code and docs disagree	Stop. Present both interpretations. Ask the user which is authoritative. Record the answer.
Docs are silent	Code-inferred design stands. Record the documentation gap as a finding.

Do not proceed past this gate without a clear, unambiguous design intent.

Phase 3: Gap

With the inferred design crystallized, analyze class-by-class, element-by-element within the scope.

For each class, examine every code element:

Element	Check Against Design
Class declaration	Name, base class, interfaces — does it declare what the design says it should be?
Constructor	Dependencies injected — consistent with structural role? Missing? Extra?
Public methods	Does public surface match expected shape? Methods that shouldn't be public? Missing methods the contract implies?
Private methods	Do they serve the declared role, or reveal a hidden secondary responsibility?
Fields/Properties	State held — consistent with stateless/stateful expectation?
Control flow	Behavioral complexity — does it match the role's expected complexity?
Type relationships	What it references, what references it — does coupling match design expectations?

Classify each gap:

Classification	Meaning
Role Confusion	The element serves a different structural role than the design implies
Structural Deviation	The element exists but doesn't match the inferred design shape
Missing Element	The design implies something should exist here but doesn't
Excess Element	Something exists that the design doesn't account for

Severity by design coherence impact (not bug risk):

Severity	Criteria
Critical	Class identity contradicts inferred design
High	Public contract element deviates from design expectation
Medium	Internal structure doesn't match pattern expectation
Low	Naming, organization, minor structural inconsistency

Detailed gap analysis methodology is in references/gap-methodology.md.

Phase 4: Remediate

Produce a prioritized remediation list. Ordering logic:

1. Role Confusion first — a class that doesn't know what it is cascades errors into every other fix
2. Missing Elements second — structural holes other classes may be working around
3. Structural Deviations third — exist but wrong-shaped
4. Excess Elements last — may require design decisions, safest to defer

Each remediation entry includes:

• Gap ID it addresses
• Specific change: rename, move, extract, inline, add, remove, restructure
• Affected classes
• Whether isolated or has downstream ripple effects

Phase 5: Approve (Human Gate)

Present the full analysis in the current output style:

• Inferred design statement (from Phase 1)
• Reconciliation notes (from Phase 2)
• Gap findings table (from Phase 3)
• Remediation plan (from Phase 4)

Wait for explicit user approval. On rejection or revision, loop back to the relevant phase.

Phase 6: Plan

On approval, enter planning mode. Produce an implementation plan structured for execution in a fresh context window:

• The inferred design statement (so the executor understands WHY)
• References to specific files and line ranges
• Ordered remediation steps as discrete tasks
• Verification criteria per task
• Dependencies between tasks

Invoke writing-plans if available for plan structuring.

Scope Resolution

The scope is bound to the user's request. If ambiguous, ask for clarification before starting Phase 1.

Valid scopes:

• A single class or file
• A namespace or directory
• A vertical slice / flow across layers
• A project or assembly
• "Full stack" — systematic sweep (execute scope-by-scope)

For "full stack" requests, partition the system into logical scopes and execute the full pipeline per scope sequentially.

Unit of work is always class-by-class, element-by-element — regardless of scope size.

Reference Files

• references/gap-methodology.md — Detailed detection techniques for each gap classification, with code inspection patterns and severity decision trees