Evaluate Against Architecture Principles

Overview

Grounding in architecture principles during creation prevents violations before they happen. Systematic evaluation during review catches what slipped through.

This skill serves two purposes:

1. Before creating: Read principles to ground problem framing and solution design in all 9 architecture categories
2. When reviewing: Systematically evaluate documents against all architecture principle categories for compliance verification

Both prevent technical debt - grounding prevents violations during creation, evaluation catches them during review.

When to Use

Use BEFORE creating to ground thinking in principles:

• User explicitly references principles - "using our architecture principles", "following the principles", "check against principles"
• Fresh conversation with design work - Empty context and user requests design, requirements, or architecture work
• Any design-type work - Starting a new requirements document (PRD, user story)
• Framing a design problem or solution approach
• Planning implementation tasks or file structure
• Brainstorming architectural approaches

Use when reviewing for compliance verification:

• Completed requirements documents (PRDs, user stories)
• Finished design documents
• Written implementation plans
• Code review requests for architectural patterns

Do NOT skip this skill because:

• "I'll check principles during review" → Grounding happens during creation, not after
• "Document seems simple" → Simple docs still need safety, naming, MVP checks
• "Only need to check MVP principles" → MVP docs still define data models, interfaces
• "Time pressure" → Systematic evaluation takes 5-10 minutes, prevents weeks of rework
• "I already know the principles" → Reading refreshes context, prevents blind spots

Workflows

Workflow: Before Creating

When starting to create a new document:

1. Read principles - Read ARCHITECTURE-PRINCIPLES.md to refresh all 9 categories
2. Internalize context - Focus on categories relevant to your document type (see Document Type Guidance)
3. Create grounded - Write with principles actively in mind, referencing as needed

Purpose: Ground thinking in principles BEFORE structure locks in. Prevents violations from becoming embedded assumptions.

Workflow: When Reviewing

When evaluating an existing document:

1. Read principles - Read ARCHITECTURE-PRINCIPLES.md
2. Extract citations - Run citation-manager extract links <file-path> to get full context
3. Systematic evaluation - Follow Evaluation Checklist below, checking ALL categories
4. Structured output - Provide evaluation in standard format

Purpose: Catch violations systematically before they reach production.

Mandatory First Step (Review Mode)

<critical-instruction> Read [ARCHITECTURE-PRINCIPLES.md](../../../ARCHITECTURE-PRINCIPLES.md) </critical-instruction>

BEFORE evaluating ANY document, extract citation context:

citation-manager extract links <file-path>

This command:

• Extracts all wiki-linked documents referenced in the file
• Provides full context for evaluation
• Reveals violations hidden in linked content

Do NOT skip this step. Evaluating without citation context = incomplete evaluation.

If citation-manager finds 0 links:

• This is still useful information (no related docs to consider)
• Document this in your evaluation report
• Continue with systematic evaluation
• Do NOT interpret 0 results as permission to skip the command

Evaluation Checklist

MANDATORY: Use TodoWrite to create todos for EACH category below.

This is not optional. TodoWrite ensures:

• You don't skip categories under pressure
• User can track evaluation progress
• No category gets "mentally checked" but not actually evaluated

Check EVERY category systematically.

Phase 1: Extract Context

• [ ] Run citation-manager extract links <file-path>
• [ ] Read all extracted content
• [ ] Identify document type (Requirements/Design/Implementation)

Phase 2: Systematic Evaluation

Evaluate against ALL categories below. Mark "✅ Compliant", "❌ Violates", or "➖ Not mentioned in doc".

IMPORTANT: "➖ Not mentioned" means potential gap, not "compliant by default".

• If document lacks detail on a principle, that's a finding

• Recommend adding detail in your recommendations section

• Don't interpret silence as compliance

• [ ] Modular Design: Single responsibility, loose coupling, replaceable parts

• [ ] Data-First Design: Primitives, illegal states, explicit relationships, behavior as data

• [ ] Action-Based File Organization: Transformation naming, data contracts, primary export pattern

• [ ] Format/Interface Design: Simplicity first, progressive defaults, interface segregation

• [ ] MVP Principles: MVP-first, scope adherence, simplicity, implement when needed

• [ ] Deterministic Offloading: Mechanical separation, tool-first design, no surprises

• [ ] Self-Contained Naming: Descriptive labels, immediate understanding, confusion prevention

• [ ] Safety-First Design: Backup creation, dry-run capability, input validation, fail fast

• [ ] Anti-Patterns Check: Scattered checks, branch explosion, leaky flags, hidden state

Phase 3: Structured Output

Provide evaluation in this format:

## Architecture Evaluation: <Document Name>

### Citation Context
- Extracted X linked documents
- [List key linked files]

### Principle Compliance

| Category | Status | Details |
|----------|--------|---------|
| Modular Design | ❌ Violates | Component violates single responsibility (line 15) |
| Data-First Design | ❌ Violates | Scattered type checks instead of behavior as data (lines 20-45) |
| File Organization | ➖ Not mentioned | No file structure specified |
| MVP Principles | ✅ Compliant | Scope is minimal and focused |
| ... | ... | ... |

### Critical Issues (Severity: High)
1. [Issue with specific principle citation and line numbers]
2. [Issue with specific principle citation and line numbers]

### Recommendations
1. [Specific change with principle reference]
2. [Specific change with principle reference]

### Verdict
- [ ] Ready to proceed
- [X] Requires revision

Architecture Principles Reference

The principles are defined in: ARCHITECTURE-PRINCIPLES.md %% force-extract %%

Key categories:

1. Modular Design (^modular-design-principles-definition)
2. Data-First Design (^data-first-principles-definition)
3. Action-Based File Organization (^action-based-file-organization-definition)
4. Format/Interface Design (^format-interface-design-definition)
5. MVP Principles (^mvp-principles-definition)
6. Deterministic Offloading (^deterministic-offloading-principles-definition)
7. Self-Contained Naming (^self-contained-naming-principles-definition)
8. Safety-First Design (^safety-first-principles-definition)
9. Anti-Patterns (^anti-patterns-definition)

Common Rationalizations

| Excuse | Reality | |--------|---------| | "User said 'principles' but meant generally" | User mentioned principles = trigger to read ARCHITECTURE-PRINCIPLES.md. No exceptions. | | "Fresh conversation, I can start directly" | Empty context = read principles first to ground thinking. Don't skip this step. | | "User wants quick design, no time for principles" | Fresh conversation with design work = mandatory principles read. 5 min prevents days of rework. | | "I'll check principles during review" | Grounding happens during creation. Review catches violations that cost hours to fix. | | "I already know the principles" | Reading refreshes all 9 categories, prevents blind spots under pressure. | | "Just need to start writing quickly" | 5 min reading principles prevents days of rework. Start grounded. | | "Will evaluate after first draft" | First draft locks in structure. Violations become embedded assumptions. | | "Only MVP principles are relevant" | MVP docs still define data models, interfaces, naming patterns | | "Document labeled 'MVP' = only check MVP" | "MVP" label is WARNING SIGN to check scope violations, not excuse to skip categories | | "Not enough detail to evaluate X" | Mark "➖ Not mentioned" and recommend adding detail | | "Time pressure, focus on big issues" | Systematic check takes 5-10 min, prevents weeks of rework | | "This principle doesn't apply" | Check anyway, explain why it doesn't apply in output | | "Already followed best practices" | Best practices = these principles. Check systematically. | | "Citation-manager will slow me down" | Takes 10 seconds, reveals hidden violations | | "Citation-manager found 0 links, skip it" | 0 results = useful data (no context). Still run the command. |

Document Type Guidance

Requirements Documents

Focus on:

• MVP Principles (scope, simplicity)
• Data-First Design (data models mentioned)
• Safety-First (error handling requirements)

Still check all other categories, mark "➖ Not mentioned" if truly not applicable.

Design Documents

Focus on:

• Modular Design (component boundaries)
• Data-First Design (data structures)
• Action-Based File Organization
• Interface Design

Still check all other categories.

Implementation Plans

Focus on:

• File Organization (file structure)
• Naming (file and function names)
• Safety-First (implementation safety)

Still check all other categories.

Red Flags - STOP and Re-evaluate

You're rationalizing if you think:

• "I'll just check the relevant principles"
• "This doc is too simple for full evaluation"
• "Citation-manager isn't needed here"
• "Some categories obviously don't apply"

All of these mean: Follow the checklist systematically.

Real-World Impact

Without systematic evaluation:

• MVP scope creep (10 features labeled "minimal")
• Scattered validation logic requiring refactor
• Component god objects violating single responsibility
• Missing safety checks causing data loss

With systematic evaluation:

• Violations caught in design phase (2-hour fix)
• vs. caught in production (2-week refactor)
• Clear principle citations enable quick fixes
• Complete coverage prevents "obvious in hindsight" issues