--- name: evaluate-against-architecture-principles description: Use when user references architecture principles, at start of fresh conversation with design work, before creating any requirements/design/implementation documents, or when reviewing for compliance - grounds problem framing and solution making in all 9 principle categories using citation-manager to extract full context --- # 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](../../../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](../../../ARCHITECTURE-PRINCIPLES.md) 2. **Extract citations** - Run `citation-manager extract links ` 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:** ```bash citation-manager extract links ``` 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 ` - [ ] 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: ```markdown ## Architecture Evaluation: ### 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](../../../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