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)

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

Phase 4: Findings Prioritization (MVP Lens)

MANDATORY when evaluating design documents. Optional but recommended for other document types.

After producing the structured evaluation output, filter findings before presenting to user:

1. •

   Cross-reference findings against the document's own risk assessment

   • •If the document has a Risk Assessment section, check whether each finding is already mitigated
   • •Already-mitigated findings get lower priority
2. •

   Apply MVP lens to each finding

   • •Ask: "Is this blocking the system from working, or is it hardening?"
   • •Fix now: Violates core functionality, blocks MVP, creates data loss risk, or makes illegal states representable
   • •Fix post-MVP: Improves robustness, adds polish, prevents theoretical issues, or optimizes performance
3. •

   Categorize findings

   markdown

   ### Prioritized Findings
   
   #### Fix Now (Blocking MVP)
   1. [Finding with principle citation] — [Why it blocks MVP]
   
   #### Fix Post-MVP (Hardening)
   1. [Finding with principle citation] — [Why it can wait]
   
   #### Already Mitigated
   1. [Finding] — Addressed by [risk mitigation from document]
   

4. •

   Present filtered list to user — not the raw evaluation table

   • •Lead with "Fix Now" items (actionable)
   • •Mention "Fix Post-MVP" count without detail unless asked
   • •Note "Already Mitigated" as confirmation, not action items

Why this matters: Raw architecture evaluations produce 9+ findings. Presenting all of them equally overwhelms and delays delivery. MVP filtering ensures the user acts on what matters now and defers what doesn't.

Do NOT skip this because:

• •"All findings are important" — True, but not all are urgent. Prioritize.
• •"User should see everything" — They will, categorized. Not as a flat list.
• •"This adds overhead" — 2 minutes of categorization saves 30 minutes of discussion about non-blocking items.

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

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