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)

Read [ARCHITECTURE-PRINCIPLES.md](../../../ARCHITECTURE-PRINCIPLES.md)

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