AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection

Technical Anti-patterns (Red Flag Patterns)

Immediately stop and reconsider design when detecting the following patterns:

Code Quality Anti-patterns

1. Writing similar code 3 or more times - Violates Rule of Three
2. Multiple responsibilities mixed in a single file - Violates Single Responsibility Principle (SRP)
3. Defining same content in multiple files - Violates DRY principle
4. Making changes without checking dependencies - Potential for unexpected impacts
5. Disabling code with comments - Should use version control
6. Error suppression - Hiding problems creates technical debt
7. Bypassing safety mechanisms (type systems, validation, contracts) - Circumventing language's correctness guarantees

Design Anti-patterns

• "Make it work for now" thinking - Accumulation of technical debt
• Patchwork implementation - Unplanned additions to existing code
• Optimistic implementation of uncertain technology - Designing unknown elements assuming "it'll probably work"
• Symptomatic fixes - Surface-level fixes that don't solve root causes
• Unplanned large-scale changes - Lack of incremental approach

Fail-Fast Fallback Design Principles

Core Principle

Make all errors visible and traceable with full context. Prioritize primary code reliability over fallback implementations. Excessive fallback mechanisms mask errors and make debugging difficult.

Implementation Guidelines

Default Approach

• Propagate all errors explicitly unless a Design Doc specifies a fallback
• Make failures explicit: Errors should be visible and traceable
• Preserve error context: Include original error information when re-throwing

When Fallbacks Are Acceptable

• Only with explicit Design Doc approval: Document why fallback is necessary
• Business-critical continuity: When partial functionality is better than none
• Graceful degradation paths: Clearly defined degraded service levels

Layer Responsibilities

• Infrastructure Layer:

  • Always throw errors upward
  • No business logic decisions
  • Provide detailed error context

• Application Layer:

  • Make business-driven error handling decisions
  • Implement fallbacks only when specified in requirements
  • Log all fallback activations for monitoring

Error Masking Detection

Review Triggers (require design review):

• Writing 3rd error handler in the same feature
• Multiple error handling blocks in single function/method
• Nested error handling structures
• Error handlers that return default values without logging

Before Implementing Any Fallback:

1. Verify Design Doc explicitly defines this fallback
2. Document the business justification
3. Ensure error is logged with full context
4. Add monitoring/alerting for fallback activation

Implementation Pattern

AVOID: Silent fallback that hides errors
    <handle error>:
        return DEFAULT_VALUE  // Error hidden, debugging impossible

PREFERRED: Explicit failure with context
    <handle error>:
        log_error('Operation failed', context, error)
        <propagate error>  // Re-throw exception, return Error, return error tuple

Adaptation: Use language-appropriate error handling (exceptions, Result types, error tuples, etc.)

Rule of Three - Criteria for Code Duplication

How to handle duplicate code based on Martin Fowler's "Refactoring":

Criteria for Commonalization

Cases for Commonalization

• Business logic duplication
• Complex processing algorithms
• Areas likely requiring bulk changes
• Validation rules

Cases to Avoid Commonalization

• Accidental matches (coincidentally same code)
• Possibility of evolving in different directions
• Significant readability decrease from commonalization
• Simple helpers in test code

Common Failure Patterns and Avoidance Methods

Pattern 1: Error Fix Chain

Symptom: Fixing one error causes new errors Cause: Surface-level fixes without understanding root cause Avoidance: Identify root cause with 5 Whys before fixing

Pattern 2: Circumventing Correctness Guarantees

Symptom: Bypassing safety mechanisms (type systems, validation, contracts) Cause: Impulse to avoid correctness errors Avoidance: Use language-appropriate safety mechanisms (static checking, runtime validation, contracts, assertions)

Pattern 3: Implementation Without Sufficient Testing

Symptom: Many bugs after implementation Cause: Ignoring Red-Green-Refactor process Avoidance: Always start with failing tests

Pattern 4: Ignoring Technical Uncertainty

Symptom: Frequent unexpected errors when introducing new technology Cause: Assuming "it should work according to official documentation" without prior investigation Avoidance:

• Record certainty evaluation at the beginning of task files

  Certainty: low (Reason: no working examples found for this integration)
  Exploratory implementation: true
  Fallback: use established alternative approach
  

• For low certainty cases, create minimal verification code first

Pattern 5: Insufficient Existing Code Investigation

Symptom: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns Cause: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness Avoidance Methods:

• Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords)
• Similar functionality found → Use that implementation (do not create new implementation)
• Similar functionality is technical debt → Create ADR improvement proposal before implementation
• No similar functionality exists → Implement new functionality following existing design philosophy
• Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
• Reference representativeness check: When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting — nearby files alone are an insufficient basis

Debugging Techniques

1. Error Analysis Procedure

1. Read error message (first line) accurately
2. Focus on first and last of stack trace
3. Identify first line where your code appears

2. 5 Whys - Root Cause Analysis

Trace the failure through repeated "why" questions until the root cause is actionable.

3. Minimal Reproduction Code

To isolate problems, attempt reproduction with minimal code:

• Remove unrelated parts
• Replace external dependencies with mocks
• Create minimal configuration that reproduces problem

4. Debug Log Output

Include operation context, relevant input data, current state, and timestamp.

Quality Assurance Mechanism Awareness

Before executing quality checks, identify what quality mechanisms exist for the change area:

• Primary detection: inspect the change area's file types, project manifest, and configuration to identify applicable quality tools
  • Check CI pipeline definitions for checks that cover the affected paths
  • Check for domain-specific linter or validator configurations (e.g., schema validators, API spec validators, configuration file linters)
  • Check for domain-specific constraints in project configuration (naming rules, length limits, format requirements)
• Supplementary hint: IF task file specifies Quality Assurance Mechanisms → use them as additional hints for which domain-specific checks to look for
• Include discovered domain-specific checks alongside standard quality phases below

Quality Check Workflow

Universal quality assurance phases applicable to all languages:

Phase 1: Static Analysis

1. Code Style Checking: Verify adherence to style guidelines
2. Code Formatting: Ensure consistent formatting
3. Unused Code Detection: Identify dead code and unused imports/variables
4. Static Type Checking: Verify type correctness (for statically typed languages)
5. Static Analysis: Detect potential bugs, security issues, code smells

Phase 2: Build Verification

1. Compilation/Build: Verify code builds successfully (for compiled languages)
2. Dependency Resolution: Ensure all dependencies are available and compatible
3. Resource Validation: Check configuration files, assets are valid

Phase 3: Testing

1. Unit Tests: Run all unit tests
2. Integration Tests: Run integration tests
3. Test Coverage: Measure and verify coverage meets standards
4. E2E Tests: Run end-to-end tests

Phase 4: Final Quality Gate

All checks must pass before proceeding:

• Zero static analysis errors
• Build succeeds
• All tests pass
• Coverage meets project-configured threshold

Quality Check Pattern (Language-Agnostic)

Workflow:
1. Format check → 2. Lint/Style → 3. Static analysis →
4. Build/Compile → 5. Unit tests → 6. Coverage check →
7. Integration tests → 8. Final gate

Auto-fix capabilities (when available):
- Format auto-fix
- Lint auto-fix
- Dependency/import organization
- Simple code smell corrections

Situations Requiring Technical Decisions

Timing of Abstraction

• Extract patterns after writing concrete implementation 3 times
• Be conscious of YAGNI, implement only currently needed features
• Prioritize current simplicity over future extensibility

Performance vs Readability

• Prioritize readability unless profiling identifies a measurable bottleneck (e.g., response time exceeding SLA, memory exceeding allocation)
• Measure before optimizing
• Document reason with comments when optimizing

Granularity of Contracts and Interfaces

• Overly detailed contracts reduce maintainability
• Design interfaces where each method maps to a single domain operation and parameter types use domain vocabulary
• Use abstraction mechanisms to reduce duplication

Scope Expansion

• Apply implementation/edit instructions to the user's or task's specified scope. Escalate before expanding it.
• Treat explicit quantities and targets ("one", "this file", "only X") as boundaries
• Copy/move/mirror requests preserve content verbatim; edit content only when requested
• Port/translation requests preserve intent and behavior; adapt only what the destination context requires
• Before changing related files, symmetric locations, adjacent behavior, or adding helpful extras, escalate with the proposed expansion

Implementation Completeness Assurance

Impact Analysis: Mandatory 3-Stage Process

Complete these stages sequentially before any implementation:

1. Discovery - Identify all affected code:

• Implementation references (imports, calls, instantiations)
• Interface dependencies (contracts, types, data structures)
• Test coverage
• Configuration (build configs, env settings, feature flags)
• Documentation (comments, docs, diagrams)

2. Understanding - Analyze each discovered location:

• Role and purpose in the system
• Dependency direction (consumer or provider)
• Data flow (origin → transformations → destination)
• Coupling strength

3. Identification - Produce structured report:

## Impact Analysis
### Direct Impact
- [Unit]: [Reason and modification needed]

### Indirect Impact
- [System]: [Integration path → reason]

### Data Flow
[Source] → [Transformation] → [Consumer]

### Risk Assessment
- High: [Complex dependencies, fragile areas]
- Medium: [Moderate coupling, test gaps]
- Low: [Isolated, well-tested areas]

### Implementation Order
1. [Start with lowest risk or deepest dependency]
2. [...]

Critical: Do not implement until all 3 stages are documented

Unused Code Deletion

When unused code is detected:

• Will it be used in this work? Yes → Implement now | No → Delete now (Git preserves)
• Applies to: Code, tests, docs, configs, assets

Existing Code Modification

In use? No → Delete
       Yes → Working? No → Delete + Reimplement
                     Yes → Fix/Extend

Principle: Prefer clean implementation over patching broken code

Language-Agnostic Coding Principles

Core Philosophy

1. Maintainability over Speed: Prioritize long-term code health over initial development velocity
2. Simplicity First: Choose the simplest solution that meets requirements (YAGNI principle)
3. Minimum Surface for Required Coverage: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point.
4. Explicit over Implicit: Make intentions clear through code structure and naming
5. Delete over Comment: Remove unused code instead of commenting it out

Code Quality

Continuous Improvement

• Refactor related code within each change set — address style, naming, or structure issues in the files being modified
• Improve code structure incrementally
• Keep the codebase lean and focused
• Delete unused code immediately

Readability

• Use meaningful, descriptive names drawn from the problem domain
• Use full words in names; abbreviations are acceptable only when widely recognized in the domain
• Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)
• Extract magic numbers and strings into named constants
• Keep code self-documenting where possible

Function Design

Parameter Management

• Recommended: 0-2 parameters per function
• For 3+ parameters: Use objects, structs, or dictionaries to group related parameters
• Example (conceptual):

  // Instead of: createUser(name, email, age, city, country)
  // Use: createUser(userData)
  

Single Responsibility

• Each function should do one thing well
• Keep functions small and focused (typically < 50 lines)
• Extract complex logic into separate, well-named functions
• Functions should have a single level of abstraction

Function Organization

• Pure functions when possible (no side effects)
• Separate data transformation from side effects
• Use early returns to reduce nesting
• Keep nesting to a maximum of 3 levels; use early returns or extracted functions to flatten deeper nesting

Error Handling

Error Management Principles

• Always handle errors: Log with context or propagate explicitly
• Log appropriately: Include context for debugging
• Protect sensitive data: Mask or exclude passwords, tokens, PII from logs
• Fail fast: Detect and report errors as early as possible

Error Propagation

• Use language-appropriate error handling mechanisms
• Propagate errors to appropriate handling levels
• Provide meaningful error messages
• Include error context when re-throwing

Dependency Management

Loose Coupling via Parameterized Dependencies

• Inject external dependencies as parameters (constructor injection for classes, function parameters for procedural/functional code)
• Depend on abstractions, not concrete implementations
• Minimize inter-module dependencies
• Facilitate testing through mockable dependencies

Reference Representativeness

Verifying References Before Adoption

When adopting patterns, APIs, or dependencies from existing code:

• IF referencing only 2-3 nearby files → THEN confirm the pattern is representative by checking usage across the repository before adopting
• IF multiple approaches coexist in the repository → THEN identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient
• IF adopting an external dependency (library, plugin, SDK) → THEN verify repository-wide usage distribution for the same dependency; if the appropriate version cannot be determined from repository state alone, escalate
• IF following an existing pattern → THEN state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update)

Principle

Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model.

Performance Considerations

Optimization Approach

• Measure first: Profile before optimizing
• Focus on algorithms: Algorithmic complexity > micro-optimizations
• Use appropriate data structures: Choose based on access patterns
• Resource management: Handle memory, connections, and files properly

When to Optimize

• After identifying actual bottlenecks through profiling
• When performance issues are measurable
• Optimize only after measurable bottlenecks are identified, not during initial development

Code Organization

Structural Principles

• Group related functionality: Keep related code together
• Separate concerns: Domain logic, data access, presentation
• Consistent naming: Follow project conventions
• Module cohesion: High cohesion within modules, low coupling between

File Organization

• One primary responsibility per file
• Logical grouping of related functions/classes
• Clear folder structure reflecting architecture
• Avoid "god files" (files > 500 lines)

Commenting Principles

Default: code first

Names, types, and structure are the primary medium. A comment earns its place only by carrying information the code itself cannot express. When in doubt, improve the name instead of adding a comment.

The test for every comment

A comment is justified only if it answers one of these:

• Why: reasoning, trade-off, or constraint behind a non-obvious decision
• Limitation / edge case: a boundary a reader cannot infer from the code
• Public API contract: behavior, inputs, outputs of an exported interface

One comment per decision. If a comment restates what the names and control flow already show, delete it and rename instead.

Comment Scope

• Comment the why, limits, and public contracts (per the test above); let names and structure carry everything else, including the "how"
• Record historical context in version control commit messages, not in comments
• Delete commented-out code (retrieve from git history when needed)

Comment Quality

• Write comments that remain accurate regardless of future code changes; avoid references to dates, versions, or temporary state
• Update comments when changing code
• Use proper grammar and formatting
• Write for future maintainers

Refactoring Approach

Safe Refactoring

• Small steps: Make one change at a time
• Maintain working state: Keep tests passing
• Verify behavior: Run tests after each change
• Incremental improvement: Don't aim for perfection immediately

Refactoring Triggers

• Code duplication (DRY principle)
• Functions > 50 lines
• Complex conditional logic
• Unclear naming or structure

Testing Considerations

Testability

• Write testable code from the start
• Avoid hidden dependencies
• Keep side effects explicit
• Design for parameterized dependencies

Test-Driven Development

• Write tests before implementation when appropriate
• Keep tests simple and focused
• Test behavior, not implementation
• Maintain test quality equal to production code

Security Principles

Secure Defaults

• Store credentials and secrets through environment variables or dedicated secret managers
• Use parameterized queries (prepared statements) for all database access
• Use established cryptographic libraries provided by the language or framework
• Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators
• Encrypt sensitive data at rest and in transit using standard protocols

Input and Output Boundaries

• Validate all external input at system entry points for expected format, type, and length
• Encode output appropriately for its rendering context (HTML, SQL, shell, URL)
• Return only information necessary for the caller in error responses; log detailed diagnostics server-side

Access Control

• Apply authentication to all entry points that handle user data or trigger state changes
• Verify authorization for each resource access, not only at the entry point
• Grant only the permissions required for the operation (files, database connections, API scopes)

Knowledge Cutoff Supplement (2026-03)

• OWASP Top 10:2025 shifted from symptoms to root causes; added "Software Supply Chain Failures" (A03) and "Mishandling of Exceptional Conditions" (A10)
• Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets
• OpenSSF published "Security-Focused Guide for AI Code Assistant Instructions" — recommends language-specific, actionable constraints over generic advice
• For detailed detection patterns, see references/security-checks.md

Documentation

Code Documentation

• Document public APIs and interfaces
• Include usage examples for complex functionality
• Maintain README files for modules
• Update documentation in the same commit that changes the corresponding behavior

Architecture Documentation

• Document high-level design decisions
• Explain integration points
• Clarify data flows and boundaries
• Record trade-offs and alternatives considered

Version Control Practices

Commit Practices

• Make atomic, focused commits
• Write clear, descriptive commit messages
• Commit working code (passes tests)
• Commit only production-ready code; store secrets in environment variables or secret managers

Code Review Readiness

• Self-review before requesting review
• Keep changes focused and reviewable
• Provide context in pull request descriptions
• Respond to feedback constructively

Language-Specific Adaptations

While these principles are language-agnostic, adapt them to your specific programming language:

• Static typing: Use strong types when available
• Dynamic typing: Add runtime validation
• OOP languages: Apply SOLID principles
• Functional languages: Prefer pure functions and immutability
• Concurrency: Follow language-specific patterns for thread safety

Documentation Creation Criteria

Templates

• prd-template.md - Product Requirements Document template
• adr-template.md - Architecture Decision Record template
• ui-spec-template.md - UI Specification template (frontend/fullstack features)
• design-template.md - Technical Design Document template
• plan-template.md - Work Plan template
• task-template.md - Task file template for implementation tasks

Creation Decision Matrix

ADR Creation Conditions (Required if Any Apply)

1. Contract System Changes

• Adding nested contracts with 3+ levels: Contract A { Contract B { Contract C { field: T } } }
  • Rationale: Deep nesting has high complexity and wide impact scope
• Changing/deleting contracts used in 3+ locations
  • Rationale: Multiple location impacts require careful consideration
• Contract responsibility changes (e.g., DTO→Entity, Request→Domain)
  • Rationale: Conceptual model changes affect design philosophy

2. Data Flow Changes

• Storage location changes (DB→File, Memory→Cache)
• Processing order changes with 3+ steps
  • Example: "Input→Validation→Save" to "Input→Save→Async Validation"
• Data passing method changes (parameter passing→shared state, direct reference→event-based communication)

3. Architecture Changes

• Layer addition, responsibility changes, component relocation

4. External Dependency Changes

• Library/framework/external API introduction or replacement

5. Complex Implementation Logic (Regardless of Scale)

• Managing 3+ states
• Coordinating 5+ asynchronous processes

Detailed Document Definitions

PRD (Product Requirements Document)

Purpose: Define business requirements and user value

Includes:

• Business requirements and user value
• Success metrics and KPIs (each metric specifies a numeric target and measurement method)
• User stories and use cases
• MoSCoW prioritization (Must/Should/Could/Won't)
• Acceptance criteria with sequential IDs (AC-001, AC-002, ...) for downstream traceability
• MVP and Future phase separation
• User journey diagram (required)
• Scope boundary diagram (required)

Scope: Business requirements, user value, success metrics, user stories, and prioritization only. Implementation details belong in Design Doc, technical selection rationale in ADR, phases and task breakdown in Work Plan.

ADR (Architecture Decision Record)

Purpose: Record technical decision rationale and background

Includes:

• Decision (what was selected)
• Rationale (why that selection was made)
• Option comparison (minimum 3 options) and trade-offs
• Architecture impact
• Principled implementation guidelines (e.g., "Use dependency injection")

Scope: Decision, rationale, option comparison, architecture impact, and principled guidelines only. Implementation procedures and code examples belong in Design Doc, schedule and resource assignments in Work Plan.

UI Specification

Purpose: Define UI structure, screen transitions, component decomposition, and interaction design for frontend features

Includes:

• Screen list and transition conditions
• Component decomposition with state x display matrix (default/loading/empty/error/partial)
• Interaction definitions linked to PRD acceptance criteria (EARS format)
• Prototype management (code-based prototypes as attachments, not source of truth)
• AC traceability from PRD to screens/components
• Existing component reuse map and design tokens
• Visual acceptance criteria (golden states, layout constraints)
• Accessibility requirements (keyboard, screen reader, contrast)

Scope: Screen structure, transitions, component decomposition, interaction design, and visual acceptance criteria only. Technical implementation and API contracts belong in Design Doc, test implementation in test skeleton generation output, schedule in Work Plan.

Required Structural Elements:

• At least one component with state x display matrix and interaction table
• AC traceability table mapping PRD ACs to screens/states
• Screen list with transition conditions
• Existing component reuse map (reuse/extend/new decisions)

Prototype Code Handling:

• Prototype code provided by user is placed in docs/ui-spec/assets/{feature-name}/
• Prototype is an attachment to UI Spec, never the source of truth
• UI Spec + Design Doc are the canonical specifications

Design Document

Purpose: Define technical implementation methods in detail

Includes:

• Existing codebase analysis (required)
  • Implementation path mapping (both existing and new)
  • Integration point clarification (connection points with existing code even for new implementations)
• Technical implementation approach (vertical/horizontal/hybrid)
• Technical dependencies and implementation constraints (required implementation order)
• Interface and contract definitions
• Data flow and component design
• Acceptance criteria (each criterion specifies a verifiable condition with pass/fail threshold)
• Change impact map (clearly specify direct impact/indirect impact/no ripple effect)
• Complete enumeration of integration points
• Data contract clarification
• Agreement checklist (agreements with stakeholders)
• Code inspection evidence (inspected files/functions during investigation)
• Field propagation map (when fields cross component boundaries)
• Data representation decision (when introducing new structures)
• Applicable standards (explicit/implicit classification)
• Prerequisite ADRs (including common ADRs)
• Verification Strategy (required)
  • Correctness proof method (what "correct" means for this change, how it's verified, when)
  • Early verification point (first target to prove the approach works, success criteria, failure response)

Required Structural Elements:

Change Impact Map:
  Change Target: [Component/Feature]
  Direct Impact: [Files/Functions]
  Indirect Impact: [Data format/Processing time]
  No Ripple Effect: [Unaffected features]

Interface Change Matrix:
  Existing: [Function/method/operation name]
  New: [Function/method/operation name]
  Conversion Required: [Yes/No]
  Compatibility Method: [Approach]

Scope: Technical implementation methods, interfaces, data flow, acceptance criteria, and verification strategy only. Technology selection rationale belongs in ADR, schedule and assignments in Work Plan.

Work Plan

Purpose: Implementation task management and progress tracking

Includes:

• Task breakdown and dependencies (maximum 2 levels)
• Schedule and duration estimates
• Include test skeleton file paths produced for this work plan (integration and E2E)
• Verification Strategy summary (extracted from Design Doc)
• Final Quality Assurance Phase (required)
• Progress records (checkbox format)

Scope: Task breakdown, dependencies, schedule, verification strategy summary, and progress tracking only. Technical rationale belongs in ADR, design details in Design Doc.

Phase Division Criteria (adapt to implementation approach from Design Doc):

When Vertical Slice selected:

• Each phase = one value unit (feature, component, or migration target)
• Each phase includes its own implementation + verification per Verification Strategy

When Horizontal Slice selected:

1. Phase 1: Foundation Implementation - Contract definitions, interfaces/signatures, test preparation
2. Phase 2: Core Feature Implementation - Business logic, unit tests
3. Phase 3: Integration Implementation - External connections, presentation layer

When Hybrid selected:

• Combine vertical and horizontal as defined in Design Doc implementation approach

All approaches: Final phase is always Quality Assurance (acceptance criteria achievement, all tests passing, quality checks). Each phase's verification method follows Verification Strategy from Design Doc.

Three Elements of Task Completion Definition:

1. Implementation Complete: Code is functional
2. Quality Complete: Tests, static checks, linting pass
3. Integration Complete: Verified connection with other components

Creation Process

1. Problem Analysis: Change scale assessment, ADR condition check
   • Identify explicit and implicit project standards before investigation
2. ADR Option Consideration (ADR only): Compare 3+ options, specify trade-offs
3. Creation: Use templates, include measurable conditions
4. Approval: "Accepted" after review enables implementation

Storage Locations

*Note: Work plans are excluded by .gitignore

ADR Status

Proposed → Accepted → Deprecated/Superseded/Rejected

AI Automation Rules

• 6+ files: Suggest ADR creation
• Contract/data flow change detected: ADR mandatory
• Check existing ADRs before implementation

Diagram Requirements

Required diagrams for each document (using mermaid notation):

Common ADR Relationships

1. At creation: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
2. When missing: Consider creating necessary common ADRs
3. Design Doc: Specify common ADRs in "Prerequisite ADRs" section
4. Compliance check: Verify design aligns with common ADR decisions

External Resource Context

Purpose

AI agents understand the codebase but not the external resources surrounding it. This skill captures, in a deterministic location, the access methods to resources outside the repository so downstream work (design, planning, implementation, review) can reach them without re-asking the user.

Resources covered: design origin (where the canonical visual specification lives), design system (component library and tokens), guidelines (usage docs, accessibility rules), visual verification environment (how to confirm rendering), database schema source, migration history, secret store location, API schema source (OpenAPI / proto / GraphQL SDL), mock environment, IaC source, environment configuration.

Scope Boundaries

In scope: hearing protocol, storage location, single-source-of-truth ownership rule, reference protocol for downstream consumers.

Out of scope: enforcing that captured resources are correct or current — verification belongs to the agent that consumes the resource. Generating the resources themselves (e.g., creating a DESIGN.md from scratch).

Storage Locations (Two-Tier)

Single Source of Truth Rule

The project tier owns environment facts. Feature-tier sections list only feature-specific identifiers (node id within the design source, specific endpoint path within the API, specific IaC module name) and reference project-tier entries by label; URLs, MCP names, and access commands remain in the project-tier file. When the environment changes, only the project-tier file is updated.

Example feature-tier entry uses the table format defined in references/template.md: a row with the project-tier label in the first column and the feature-specific identifier in the second column.

Hearing Protocol

When to Hear

Domain Routing

Load the domain reference matching the current task:

Each domain reference defines the axes and the question template.

Two-Phase Hearing

1. Structured hearing — for each axis defined in the domain reference, present the user with AskUserQuestion using the choices listed there (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command).

2. Self-declaration — after the structured axes, present a single AskUserQuestion: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If the user describes additional resources, append them to the storage file under an "Additional resources" subsection.

The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis.

Storage Protocol

After hearing completes:

1. Build the project-tier content from the answers. Use references/template.md as the structure.
2. Write to docs/project-context/external-resources.md. Create the directory if absent.
3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's ## External Resources Used section with the feature-tier subset (label references + feature-specific identifiers only).
4. Report the file paths back to the calling workflow.

Reference Protocol (For Downstream Consumers)

Agents that load this skill consult resources in this order:

1. Read docs/project-context/external-resources.md first (if present) to learn what is available and how to access it.
2. Read the target UI Spec or Design Doc's ## External Resources Used section for feature-specific identifiers.
3. Use the access method declared in the project tier (e.g., the named MCP, the URL, the file path) to fetch the actual resource content.

Agents that only need to consult the saved file as input data (not actively hear) can read it directly without loading this skill — frontmatter declaration is reserved for agents that may need to trigger hearing or interpret the protocol semantics.

Output Format

The project-tier file follows the structure in references/template.md. The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically.

For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context).

Quality Checklist

• Each axis answered has both a presence indicator and an access method, or is marked "Not applicable"
• Self-declaration phase ran even when all structured axes were "Not applicable"
• Project-tier file does not contain feature-specific identifiers
• Feature-tier sections reference project-tier entries by label, not by duplicating URLs / MCP names
• When the project file already existed, the update decision (no / yes-full / yes-diff-only) was confirmed before any write

References

• references/frontend.md — Frontend domain axes
• references/backend.md — Backend domain axes
• references/api.md — API contract domain axes
• references/infra.md — Infrastructure domain axes
• references/template.md — Project-tier and feature-tier structure templates

AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend)

Technical Anti-patterns (Red Flag Patterns)

Immediately stop and reconsider design when detecting the following patterns:

Code Quality Anti-patterns

1. Writing similar code 3 or more times - Violates Rule of Three
2. Multiple responsibilities mixed in a single component - Violates Single Responsibility Principle (SRP)
3. Defining same content in multiple components - Violates DRY principle
4. Making changes without checking dependencies - Potential for unexpected impacts
5. Disabling code with comments - Should use version control
6. Error suppression - Hiding problems creates technical debt
7. Excessive use of type assertions (as) - Abandoning type safety
8. Prop drilling through 3+ levels - Should use Context API or state management
9. Massive components (300+ lines) - Split into smaller components

Design Anti-patterns

• "Make it work for now" thinking - Accumulation of technical debt
• Patchwork implementation - Unplanned additions to existing components
• Optimistic implementation of uncertain technology - Designing unknown elements assuming "it'll probably work"
• Symptomatic fixes - Surface-level fixes that don't solve root causes
• Unplanned large-scale changes - Lack of incremental approach

Fallback Design Principles

Core Principle: Fail-Fast

Design philosophy that prioritizes improving primary code reliability over fallback implementations.

Criteria for Fallback Implementation

• Fallback rule: Implement fallbacks only when explicitly defined in Design Doc
• Layer Responsibilities:
  • Component Layer: Use Error Boundary for error handling
  • Hook Layer: Implement decisions based on business requirements

Detection of Excessive Fallbacks

• Require design review when writing the 3rd catch statement in the same feature
• Verify Design Doc definition before implementing fallbacks
• Properly log errors and make failures explicit

Rule of Three - Criteria for Code Duplication

How to handle duplicate code based on Martin Fowler's "Refactoring":

Criteria for Commonalization

Cases for Commonalization

• Business logic duplication
• Complex processing algorithms
• Component patterns (form fields, cards, etc.)
• Custom hooks
• Validation rules

Cases to Avoid Commonalization

• Accidental matches (coincidentally same code)
• Possibility of evolving in different directions
• Significant readability decrease from commonalization
• Simple helpers in test code

Implementation Example

// 1st-2nd occurrence: keep separate, no commonalization yet
function UserEmailInput() { /* ... */ }
function ContactEmailInput() { /* ... */ }

// Commonalize on 3rd occurrence
function EmailInput({ context }: { context: 'user' | 'contact' | 'admin' }) { /* ... */ }

Common Failure Patterns and Avoidance Methods

Pattern 1: Error Fix Chain

Symptom: Fixing one error causes new errors Cause: Surface-level fixes without understanding root cause Avoidance: Identify root cause with 5 Whys before fixing

Pattern 2: Abandoning Type Safety

Symptom: Excessive use of any type or as Cause: Impulse to avoid type errors Avoidance: Handle safely with unknown type and type guards

Pattern 3: Implementation Without Sufficient Testing

Symptom: Many bugs after implementation Cause: Ignoring Red-Green-Refactor process Avoidance: Always start with failing tests

Pattern 4: Ignoring Technical Uncertainty

Symptom: Frequent unexpected errors when introducing new technology Cause: Assuming "it should work according to official documentation" without prior investigation Avoidance:

• Record certainty evaluation at the beginning of task files

  Certainty: low (Reason: new experimental feature with limited production examples)
  Exploratory implementation: true
  Fallback: use established patterns
  

• For low certainty cases, create minimal verification code first

Pattern 5: Insufficient Existing Code Investigation

Symptom: Duplicate implementations, architecture inconsistency, integration failures Cause: Insufficient understanding of existing code before implementation Avoidance Methods:

• Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords)
• Similar functionality found → Use that implementation (do not create new implementation)
• Similar functionality is technical debt → Create ADR improvement proposal before implementation
• No similar functionality exists → Implement new functionality following existing design philosophy
• Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc

Debugging Techniques

1. Error Analysis Procedure

1. Read error message (first line) accurately
2. Focus on first and last of stack trace
3. Identify first line where your code appears
4. Check React DevTools for component hierarchy

2. 5 Whys - Root Cause Analysis

Symptom: Component not rendering
Why1: Props are undefined → Why2: Parent component didn't pass props
Why3: Parent using old prop names → Why4: Component interface was updated
Why5: No update to parent after refactoring
Root cause: Incomplete refactoring, missing call-site updates

3. Minimal Reproduction Code

To isolate problems, attempt reproduction with minimal code:

• Remove unrelated components
• Replace API calls with mocks
• Create minimal configuration that reproduces problem
• Use React DevTools to inspect component tree

4. Debug Log Output (temporary)

Add structured debug logs to isolate the issue, then remove them before commit (per "Delete debug console.log()" in typescript-rules):

console.log('DEBUG:', {
  context: 'user-form-submission',
  props: { email, name },
  state: currentState,
  timestamp: new Date().toISOString()
})

Quality Check Workflow

Read package.json scripts and run them with the project's package manager (packageManager field). Map the project's actual script names to the phases below — do not assume fixed names.

Phases (run in order)

1. Lint/format — the project's formatter + linter (e.g., Biome, or ESLint + Prettier)
2. Type check — type check without emit
3. Build — production build
4. Test — unit/integration tests
5. Coverage — coverage run when the task added or changed behavior

Troubleshooting

• Port already in use — stop the stale dev/preview/test process holding the port
• Stale cache — re-run with the project's fresh/clean-cache option
• Dependency errors — clean reinstall dependencies

Situations Requiring Technical Decisions

Timing of Abstraction

• Extract patterns after writing concrete implementation 3 times
• Be conscious of YAGNI, implement only currently needed features
• Prioritize current simplicity over future extensibility

Performance vs Readability

• Prioritize readability unless React DevTools Profiler identifies a measurable bottleneck (e.g., render time exceeding 16ms, unnecessary re-renders)
• Measure before optimizing with React DevTools Profiler
• Document reason with comments when optimizing

Granularity of Component/Type Definitions

• Overly detailed components/types reduce maintainability
• Design components that appropriately express UI patterns
• Use composition over inheritance

Implementation Completeness Assurance

Required Procedure for Impact Analysis

Completion Criteria: Complete all 3 stages

1. Discovery

Grep -n "ComponentName\|hookName" -o content
Grep -n "importedFunction" -o content
Grep -n "propsType\|StateType" -o content

2. Understanding

Mandatory: Read all discovered files and include necessary parts in context:

• Caller's purpose and context
• Component hierarchy
• Data flow: Props → State → Event handlers → Callbacks

3. Identification

Structured impact report (mandatory):

## Impact Analysis
### Direct Impact: ComponentA, ComponentB (with reasons)
### Indirect Impact: FeatureX, PageY (with integration paths)
### Processing Flow: Props → Render → Events → Callbacks

Important: Execute all 3 stages to completion

Unused Code Deletion Rule

When unused code is detected → Will it be used?

• Yes → Implement immediately (no deferral allowed)
• No → Delete immediately (remains in Git history)

Target: Components, hooks, utilities, documentation, configuration files

Existing Code Deletion Decision Flow

In use? No → Delete immediately (remains in Git history)
       Yes → Working? No → Delete + Reimplement
                     Yes → Fix

Implementation Strategy Selection Framework (Meta-cognitive Approach)

Meta-cognitive Strategy Selection Process

Phase 1: Comprehensive Current State Analysis

Core Question: "What does the existing implementation look like?"

Analysis Framework

Architecture Analysis: Responsibility separation, data flow, dependencies, technical debt
Implementation Quality Assessment: Code quality, test coverage, performance, security
Historical Context Understanding: Current form rationale, past decision validity, constraint changes, requirement evolution

Meta-cognitive Question List

• What is the true responsibility of this implementation?
• Which parts are business essence and which derive from technical constraints?
• What dependencies or implicit preconditions are unclear from the code?
• What benefits and constraints does the current design bring?

Phase 2: Strategy Exploration and Creation

Core Question: "When determining before → after, what implementation patterns or strategies should be referenced?"

Strategy Discovery Process

Research and Exploration: Tech stack examples (WebSearch), similar projects, OSS references, literature/blogs
Creative Thinking: Strategy combinations, constraint-based design, phase division, extension point design

Reference Strategy Patterns (Creative Combinations Encouraged)

Legacy Handling Strategies:

• Strangler Pattern: Gradual migration through phased replacement
• Facade Pattern: Complexity hiding through unified interface
• Adapter Pattern: Bridge with existing systems

New Development Strategies:

• Feature-driven Development: Vertical implementation prioritizing user value
• Foundation-driven Development: Foundation-first construction prioritizing stability
• Risk-driven Development: Prioritize addressing maximum risk elements

Integration/Migration Strategies:

• Proxy Pattern: Transparent feature extension
• Decorator Pattern: Phased enhancement of existing features
• Bridge Pattern: Flexibility through abstraction

Important: The optimal solution is discovered through creative thinking according to each project's context.

Phase 3: Risk Assessment and Control

Core Question: "What risks arise when applying this to existing implementation, and what's the best way to control them?"

Risk Analysis Matrix

Technical Risks: System impact, data consistency, performance degradation, integration complexity
Operational Risks: Service availability, deployment downtime, process changes, rollback procedures
Project Risks: Schedule delays, learning costs, quality achievement, team coordination

Risk Control Strategies

Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup
Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures

Phase 4: Constraint Compatibility Verification

Core Question: "What are this project's constraints?"

Constraint Checklist

Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets
Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods
Resource Constraints: Team/skills, work hours/systems, budget, external contracts
Business Constraints: Market launch timing, customer impact, regulatory compliance

Phase 5: Implementation Approach Decision

Select optimal solution from basic implementation approaches (creative combinations encouraged):

Vertical Slice (Feature-driven)

Characteristics: Vertical implementation across all layers by feature unit Application Conditions: Features share fewer than 2 data models, each feature is independently deliverable, changes touch 3+ architecture layers Verification Method: End-user value delivery at each feature completion

Horizontal Slice (Foundation-driven)

Characteristics: Phased construction by architecture layer Application Conditions: 3+ features depend on a common foundation layer, foundation changes require stability verification before consumers can proceed Verification Method: Integrated operation verification when all foundation layers complete

Hybrid (Creative Combination)

Characteristics: Flexible combination according to project characteristics Application Conditions: Unclear requirements, need to change approach per phase, transition from prototyping to full implementation Verification Method: Verify at appropriate L1/L2/L3 levels according to each phase's goals

Phase 6: Decision Rationale Documentation

Design Doc Documentation: Record in the Design Doc's implementation approach section:

1. Selected strategy name and characteristics
2. Alternatives considered and reason for rejection
3. Risk mitigation plan (from Phase 3)
4. Constraint compliance summary (from Phase 4)
5. Verification level (L1/L2/L3) and integration point definition

Verification Level Definitions

Priority for completion verification of each task:

• L1: Functional Operation Verification - Operates as end-user feature (e.g., search executable)
• L2: Test Operation Verification - New tests added and passing
• L3: Build Success Verification - Code builds/runs without errors

Priority: L1 > L2 > L3 in order of verifiability importance

Integration Point Definitions

Define integration points according to selected strategy:

• Strangler-based: When switching between old and new systems for each feature
• Feature-driven: When users can actually use the feature
• Foundation-driven: When all architecture layers are ready and E2E tests pass
• Hybrid: When individual goals defined for each phase are achieved

Quality Checks

1. Verify at least one strategy combination beyond listed patterns was considered
2. Confirm Phase 1 analysis framework is complete before selecting strategy
3. Confirm Phase 3 risk analysis matrix is populated before implementation starts
4. Confirm Phase 4 constraint checklist is reviewed before strategy decision
5. Confirm Phase 6 documentation template is filled with selection rationale

Guidelines for Meta-cognitive Execution

1. Leverage Known Patterns: Use as starting point, explore creative combinations
2. Active WebSearch Use: Research implementation examples from similar tech stacks
3. Apply 5 Whys: Pursue root causes to grasp essence
4. Multi-perspective Evaluation: Comprehensively evaluate from each Phase 1-4 perspective

Integration and E2E Testing Principles

References

E2E test design: See references/e2e-design.md for UI Spec-driven E2E test candidate selection and browser test architecture. The reference uses Playwright as the default browser harness; substitute the project's standard when different.

Test Type Definition and Limits

Lane selection (E2E only):

• Default lane for user-facing UI journeys is fixture-e2e — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup
• Add service-integration-e2e only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely

The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa.

Behavior-First Principle

Include (High ROI)

• Business logic correctness (calculations, state transitions, data transformations)
• Data integrity and persistence behavior
• User-visible functionality completeness
• Error handling behavior (what user sees/experiences)

Redirect to Other Test Types

• External service connections → Verify via contract/interface tests
• Performance metrics → Verify via dedicated load testing
• Implementation details → Verify observable behavior instead
• UI layout specifics → Verify information availability instead

Principle: Test = User-observable behavior verifiable in isolated CI environment

ROI Calculation

ROI is used to rank candidates within the same test type (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently.

ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection
              (range: 0–120)

Higher ROI Score = higher priority within its test type. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores.

ROI Thresholds by Lane

The two E2E lanes have very different ownership costs and use independent thresholds.

Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Below-floor candidates beyond the reserved slot are not emitted, leaving budget intentionally unfilled rather than padding with low-value tests.

ROI Calculation Examples

Multi-Step User Journey Definition

A feature qualifies as containing a multi-step user journey when ALL of the following are true:

1. 2+ distinct interaction boundaries are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type:
   • Web: distinct routes/pages
   • Mobile native: distinct screens/views
   • CLI: distinct command invocations or interactive prompts
   • API: distinct API calls forming a transaction (e.g., create → confirm → finalize)
2. State carries across steps — data produced or actions taken in one step affect what the next step accepts or displays
3. The journey has a completion point — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow)

User-Facing vs Service-Internal Journeys

Multi-step journeys are classified for reserved-slot eligibility:

This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above.

Use this definition when evaluating E2E test candidates and E2E gap detection.

Test Skeleton Specification

Required Comment Patterns

Each test MUST include the following annotations:

AC: [Original acceptance criteria text]
Behavior: [Trigger] → [Process] → [Observable Result]
@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e
@lane: integration | fixture-e2e | service-integration-e2e
@dependency: none | [component names] | full-system
@complexity: low | medium | high
ROI: [score]

@lane selection rule:

• integration — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language)
• fixture-e2e — Browser-level UI verification with mocked backend / fixture-driven state
• service-integration-e2e — Browser-level or end-to-end verification against running local services or stubs

Use the project's comment syntax to wrap these annotations (e.g., // for C-family, # for Python/Ruby/Shell).

Verification Items (Optional)

When verification points need explicit enumeration:

Verification items:
- [Item 1]
- [Item 2]

EARS Format Mapping

Test File Naming Convention

• Integration tests: *.int.test.* or *.integration.test.*
• fixture-e2e tests: *.fixture.e2e.test.* (or organize under tests/e2e/fixture/)
• service-integration-e2e tests: *.service.e2e.test.* (or organize under tests/e2e/service/)

The test runner or framework in the project determines the appropriate file extension. Repos that already use a single *.e2e.test.* convention may keep it as long as each file declares @lane: in its header — the lane annotation is the source of truth for routing and budget accounting.

Review Criteria

Skeleton and Implementation Consistency

Implementation Quality

Quality Standards

Required

• Each test verifies one behavior
• Clear AAA (Arrange-Act-Assert) structure
• No test interdependencies
• Deterministic execution

LLM-Friendly Context

The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate.

Core Rules

1. Use positive, executable instructions

   • State what the next agent should do.
   • Convert quality policies into positive criteria.
   • Example: "Preserve existing public API behavior across the documented compatibility cases."

2. Make vague instructions concrete

   • Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules.
   • Terms that often need clarification when they leave a decision to the next agent: appropriate, proper, related, existing behavior, optional, as needed, if needed, per convention, unresolved alternatives, TBD, placeholder.

3. Specify output shape

   • Define required sections, fields, table columns, JSON keys, or checklist items.
   • For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect.

4. Provide necessary context

   • Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions.
   • Prefer concrete file paths and section hints over broad module names.

5. Decompose complex work into verifiable steps

   • Split work with 3+ objectives or sequential dependencies into ordered steps.
   • Each step needs a checkpoint: what evidence proves it is complete.

6. Permit uncertainty explicitly

   • If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation.
   • Record unknown business, product, security, or compatibility decisions as blocking unresolved items with the input needed to resolve them.

7. Keep constraints proportionate

   • Add only constraints that reduce ambiguity or preserve a real requirement.
   • Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear.

Rewrite Patterns

Use these rewrites before treating a prompt, handoff, or artifact as complete.

Handoff Checklist

Before sending a prompt or artifact to another agent, verify:

• The target action is explicit.
• Required input paths and source artifacts are named.
• Accepted decisions and constraints are stated once, without alternate wording.
• Output format or expected status fields are specified.
• Success criteria are observable.
• Ambiguous expressions have been rewritten or marked as unresolved.
• The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items.

Generated Artifact Checklist

Before writing or finalizing a generated document:

• Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists.
• Every executable instruction names the target, action, and expected result.
• Verification steps say what to run or observe and what result proves success.
• If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning.
• If downstream work is blocked by missing information, the artifact records the missing input and escalation condition.

Test Implementation Patterns

Reference Selection

Common Principles

AAA Structure

All tests follow Arrange-Act-Assert:

• Arrange: Set up preconditions and inputs
• Act: Execute the behavior under test
• Assert: Verify the expected outcome

Test Independence

• Each test runs independently without depending on other tests
• No shared mutable state between tests
• Deterministic execution — no random or time dependencies without mocking

Naming

• Test names describe expected behavior from user perspective
• One test verifies one behavior

Language-Agnostic Testing Principles

Test-Driven Development (TDD)

The RED-GREEN-REFACTOR Cycle

Always follow this cycle:

1. RED: Write a failing test first

   • Write the test before implementation
   • Ensure the test fails for the right reason
   • Verify test can actually fail

2. GREEN: Write minimal code to pass

   • Implement just enough to make the test pass
   • Focus on making it work

3. REFACTOR: Improve code structure

   • Clean up implementation
   • Eliminate duplication
   • Improve naming and clarity
   • Keep all tests passing

4. VERIFY: Ensure all tests still pass

   • Run full test suite
   • Check for regressions
   • Validate refactoring didn't break anything

Quality Requirements

Coverage

• Treat coverage as a diagnostic signal for finding untested areas, not a target — a target gets gamed into trivial tests (Goodhart's Law)
• Concentrate tests on critical paths, business logic, and behavior whose regression would matter
• Prioritize meaningful assertions over the coverage number; any CI threshold is the project's config, not a quality goal in itself

Test Characteristics

All tests must be:

• Independent: No dependencies between tests (see Test Independence Verification for detailed criteria)
• Reproducible: Same input always produces same output
• Fast: Unit tests < 100ms each, integration tests < 1s each, full suite < 10 minutes
• Self-checking: Clear pass/fail without manual verification
• Timely: Written close to the code they test

Test Types

Unit Tests

Purpose: Test individual components in isolation

Characteristics:

• Test single function, method, or class
• Fast execution (milliseconds)
• No external dependencies
• Mock external services
• Majority of your test suite

Integration Tests

Purpose: Test interactions between components

Characteristics:

• Test multiple components together
• May include database, file system, or APIs
• Slower than unit tests
• Verify contracts between modules
• Smaller portion of test suite

End-to-End (E2E) Tests

Purpose: Test complete workflows from user perspective

Characteristics:

• Test entire application stack
• Simulate real user interactions
• Slowest test type
• Fewest in number
• Highest confidence level

Test Design Principles

AAA Pattern (Arrange-Act-Assert)

Structure every test in three clear phases:

// Arrange: Setup test data and conditions
user = createTestUser()
validator = createValidator()

// Act: Execute the code under test
result = validator.validate(user)

// Assert: Verify expected outcome
assert(result.isValid == true)

Adaptation: Apply this structure using your language's idioms (methods, functions, procedures)

One Assertion Per Concept

• Test one behavior per test case
• Multiple assertions OK if testing single concept
• Split unrelated assertions into separate tests

Example: prefer returns error when email is invalid over validates user.

Descriptive Test Names

Test names should clearly describe:

• What is being tested
• Under what conditions
• What the expected outcome is

Recommended format: "should [expected behavior] when [condition]"

Examples:

test("should return error when email is invalid")
test("should calculate discount when user is premium")
test("should throw exception when file not found")

Adaptation: Follow your project's naming convention (camelCase, snake_case, describe/it blocks)

Test Independence

Setup and Teardown

• Use setup hooks to prepare test environment
• Use teardown hooks to clean up resources
• Keep setup minimal and focused
• Ensure teardown runs even if test fails

Mocking and Test Doubles

When to Use Mocks

• Mock external dependencies: APIs, databases, file systems
• Mock slow operations: Network calls, heavy computations
• Mock unpredictable behavior: Random values, current time
• Mock unavailable services: Third-party services

Mocking Principles

• Mock at boundaries, not internally
• Keep mocks simple and focused
• Verify mock expectations when relevant
• Wrap external libraries/frameworks behind adapters and mock the adapter

Data Layer Testing

Mock Limitations for Data Layer

Mocks validate call patterns but cannot verify data layer correctness. The following pass through undetected with mock-only testing:

• Schema mismatches (table names, column names, data types)
• Query correctness (joins, filters, aggregations, grouping)
• Database constraints (NOT NULL, UNIQUE, foreign keys)
• Migration drift (schema changes that make code out of sync)

When Mocks Are Appropriate for Data Access

• Testing business logic that receives data from the data layer (mock the repository, test the service)
• Testing error handling paths (simulating connection failures, timeouts)
• Unit tests where data access is a dependency, not the subject under test

When Mocks Are Insufficient for Data Access

• Testing repository or data access implementations themselves
• Verifying query correctness (joins, filters, aggregations, grouping)
• Testing data integrity constraints
• Testing migration compatibility

Real Database Testing (Environment-Dependent)

Options for verifying data layer correctness against a real database engine:

• Containerized databases for CI environments
• In-memory databases for fast feedback (note: dialect differences may mask issues)
• Dedicated test databases with seed data

The appropriate approach depends on project environment and CI/CD capabilities.

AI-Generated Code and Schema Awareness

• AI-generated data access code has heightened schema hallucination risk
• Generated queries may use correct syntax but reference nonexistent schema elements
• Mock-based tests pass regardless of schema accuracy
• Mitigation: Design Docs should include explicit schema references so that documented schemas can be cross-checked against data access code during review

Test Quality Practices

Keep Tests Active

• Fix or delete failing tests: Resolve failures immediately
• Remove commented-out tests: Fix them or delete entirely
• Keep tests running: Broken tests lose value quickly
• Maintain test suite: Refactor tests as needed

Test Helpers and Utilities

• Create reusable test data builders
• Extract common setup into helper functions
• Build test utilities for complex scenarios
• Share helpers across test files appropriately

What to Test

Focus on Behavior

Test observable behavior, not implementation:

✓ Good: Test that function returns expected output ✓ Good: Test that correct API endpoint is called ✗ Bad: Test that internal variable was set ✗ Bad: Test order of private method calls

Test Public APIs

• Test through public interfaces
• Avoid testing private methods directly
• Test return values, outputs, exceptions
• Test side effects (database, files, logs)

Test Edge Cases

Always test:

• Boundary conditions: Min/max values, empty collections
• Error cases: Invalid input, null values, missing data
• Edge cases: Special characters, extreme values
• Happy path: Normal, expected usage

Test Quality Criteria

These criteria ensure reliable, maintainable tests.

Literal Expected Values

• Use hardcoded literal values in assertions
• Calculate expected values independently from the implementation
• If the implementation has a bug, the test catches it through independent verification
• If expected value equals mock return value unchanged, the test verifies nothing (no transformation occurred)

Result-Based Verification

• Verify final results and observable outcomes
• Assert on return values, output data, or system state changes
• For mock verification, check that correct arguments were passed

Meaningful Assertions

• Every test must include at least one assertion
• Assertions must validate observable behavior
• A test without assertions always passes and provides no value

Appropriate Mock Scope

• Mock direct external I/O dependencies: databases, HTTP clients, file systems
• Use real implementations for internal utilities and business logic
• Over-mocking reduces test value by verifying wiring instead of behavior

Boundary Value Testing

Test at boundaries of valid input ranges:

• Minimum valid value
• Maximum valid value
• Just below minimum (invalid)
• Just above maximum (invalid)
• Empty input (where applicable)

Test Independence Verification

Each test must:

• Create its own test data
• Not depend on execution order
• Clean up its own state
• Pass when run in isolation

Verification Requirements

Before Commit

• ✓ All tests pass — fix failing tests immediately
• ✓ No tests skipped or commented — delete or fix
• ✓ No debug code left in tests
• ✓ Test coverage meets standards
• ✓ No flaky tests — make deterministic
• ✓ Tests run within performance thresholds

Test Organization

File Structure

• Mirror production structure: Tests follow code organization
• Clear naming conventions: Follow project's test file patterns
  • Examples: UserService.test.*, user_service_test.*, test_user_service.*, UserServiceTests.*
• Logical grouping: Group related tests together
• Separate test types: Unit, integration, e2e in separate directories

Performance Considerations

Test Speed

• Unit tests: < 100ms each
• Integration tests: < 1s each
• Full suite: Should run frequently (< 10 minutes)

Optimization Strategies

• Run tests in parallel when possible
• Use in-memory databases for tests
• Mock expensive operations
• Split slow test suites
• Profile and optimize slow tests

Continuous Integration

CI/CD Requirements

• Run full test suite on every commit
• Block merges if tests fail
• Run tests in isolated environments
• Test on target platforms/versions

Test Reports

• Generate coverage reports
• Track test execution time
• Identify flaky tests
• Monitor test trends

Test Design Guardrails

Every Test Must

• Include at least one meaningful assertion
• Create its own test data and clean up its own state
• Pass when run in any order and in isolation
• Test observable behavior through public interfaces
• Keep test logic simple (no branching, no loops)
• Mock only external I/O boundaries, use real implementations for internal logic

Flaky Test Resolution

• Use deterministic time mocking instead of real clocks
• Use fixed seed values instead of random data
• Ensure proper resource cleanup in teardown
• Resolve race conditions with synchronization primitives

Regression Testing

Prevent Regressions

• Add test for every bug fix
• Maintain comprehensive test suite
• Run full suite regularly
• Keep all tests unless the tested functionality is removed

Legacy Code

• Add characterization tests before refactoring
• Test existing behavior first
• Gradually improve coverage
• Refactor with confidence

Testing Best Practices by Language Paradigm

Type System Utilization

For languages with static type systems:

• Leverage compile-time verification for correctness
• Focus tests on business logic and runtime behavior
• Use language's type system to prevent invalid states

For languages with dynamic typing:

• Add comprehensive runtime validation tests
• Explicitly test data contract validation
• Consider property-based testing for broader coverage

Programming Paradigm Considerations

Functional approach:

• Test pure functions thoroughly (deterministic, no side effects)
• Test side effects at system boundaries
• Leverage property-based testing for invariants

Object-oriented approach:

• Test behavior through public interfaces
• Mock dependencies via abstraction layers
• Test polymorphic behavior carefully

Common principle: Adapt testing strategy to leverage language strengths while ensuring comprehensive coverage

Documentation and Communication

Tests as Documentation

• Tests document expected behavior
• Use clear, descriptive test names
• Include examples of usage
• Show edge cases and error handling

Test Failure Messages

• Provide clear, actionable error messages
• Include actual vs expected values
• Add context about what was being tested
• Make debugging easier

TypeScript Development Rules (Frontend)

Basic Principles

• Aggressive Refactoring - Prevent technical debt and maintain health
• Delete code when no current caller exists - YAGNI principle (Kent Beck)

Comment Writing Rules

Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough. Frontend specifics:

• Comment intent, not markup: explain why a component memoizes, guards, or re-renders — not what the JSX renders
• Timeless content only: Record decisions and rationale; leave chronological history to version control

Type Safety

Absolute Rule: Replace every any with unknown, generics, or union types. any disables type checking and causes runtime errors.

any Type Alternatives (Priority Order)

1. unknown Type + Type Guards: Use for validating external input (API responses, localStorage, URL parameters)
2. Generics: When type flexibility is needed
3. Union Types・Intersection Types: Combinations of multiple types
4. Type Assertions (Last Resort): Only when type is certain

Type Guard Implementation Pattern

function isUser(value: unknown): value is User {
  return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
}

Modern Type Features

• satisfies Operator: const config = { apiUrl: '/api' } satisfies Config - Preserves inference
• const Assertion: const ROUTES = { HOME: '/' } as const satisfies Routes - Immutable and type-safe
• Branded Types: type UserId = string & { __brand: 'UserId' } - Distinguish meaning
• Template Literal Types: type EventName = \on${Capitalize}`` - Express string patterns with types

Type Safety in Frontend Implementation

• React Props/State: TypeScript manages types, unknown unnecessary
• External API Responses: Always receive as unknown, validate with type guards
• localStorage/sessionStorage: Treat as unknown, validate
• URL Parameters: Treat as unknown, validate
• Form Input (Controlled Components): Type-safe with React synthetic events

Type Safety in Data Flow

• Frontend → Backend: Props/State (Type Guaranteed) → API Request (Serialization)
• Backend → Frontend: API Response (unknown) → Type Guard → State (Type Guaranteed)

Type Complexity Management

• Props Design:
  • Props count: 3-7 props ideal (consider component splitting if exceeds 10)
  • Optional Props: 50% or less (consider default values or Context if excessive)
  • Nesting: Up to 2 levels (flatten deeper structures)
• Type Assertions: Review design if used 3+ times
• External API Types: Relax constraints and define according to reality (convert appropriately internally)

Coding Conventions

Component Design Criteria

• Function components only: Official React recommendation, optimizable by modern tooling (Exception: Error Boundary requires class component)
• Custom Hooks: Standard pattern for logic reuse and dependency injection
• Component Hierarchy: Use the project's adopted component architecture. When the project uses Atomic Design: Atoms → Molecules → Organisms → Templates → Pages. When the project uses Feature-based, Container-Presenter, or another structure: follow that structure consistently and document the chosen layering in the project README or design doc
• Co-location: Place tests, styles, and related files alongside components

Server/Client Boundary (RSC frameworks only — e.g., Next.js App Router)

• Default to server components for data fetching and rendering; isolate interactivity behind a "use client" boundary at the smallest scope that needs it
• Keep browser-only APIs (window, localStorage, event handlers) inside client components; calling them in a server component breaks the render
• N/A for client-only SPAs (e.g., Vite) — skip when the project has no server-component runtime

State Management Patterns

• Local State: useState for component-specific state
• Context API: For sharing state across component tree (theme, auth, etc.)
• Custom Hooks: Encapsulate state logic and side effects
• Server State: React Query or SWR for API data caching

Data Flow Principles

• Single Source of Truth: Each piece of state has one authoritative source
• Unidirectional Flow: Data flows top-down via props
• Immutable Updates: Use immutable patterns for state updates

// Immutable state update — always create new arrays/objects
setUsers(prev => [...prev, newUser])

Function Design

• 0-2 parameters maximum: Use object for 3+ parameters

  function createUser({ name, email, role }: CreateUserParams) {}
  

Props Design (Props-driven Approach)

• Props are the interface: Define all necessary information as props
• Pass all data dependencies as props; use Context only for cross-cutting concerns (theme, auth, locale)
• Type-safe: Always define Props type explicitly

Environment Variables

• Use the build tool's env accessor: read client-side env through the bundler's exposed accessor — Vite via import.meta.env, Next.js/CRA via prefixed process.env. Raw, unprefixed access is undefined in the browser bundle
• Only prefixed vars reach the client: build tools expose only vars carrying their public prefix; an unprefixed var is undefined in the browser. The prefix differs per tool — match the project's bundler (Vite VITE_, Next.js public NEXT_PUBLIC_, CRA REACT_APP_)
• Centrally manage env through a typed config object with a default for every variable

// Client-exposed env must carry the bundler's public prefix, or it is undefined in the browser.
// Vite:    import.meta.env.VITE_API_URL
// Next.js: process.env.NEXT_PUBLIC_API_URL
const config = {
  apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000', // adjust accessor + prefix to the project's bundler
  appName: import.meta.env.VITE_APP_NAME || 'My App'
}

Security (Client-side Constraints)

• CRITICAL: All frontend code is public and visible in browser
• All secrets stay server-side: Store API keys, tokens, and secrets on the backend only
• Exclude .env files via .gitignore
• Limit error messages to non-sensitive context

// Backend manages secrets, frontend accesses via proxy
const response = await fetch('/api/data') // Backend handles API key authentication

Dependency Injection

• Custom Hooks for dependency injection: Ensure testability and modularity

Asynchronous Processing

• Promise Handling: Always use async/await
• Error Handling: Always handle with try-catch or Error Boundary
• Type Definition: Explicitly define return value types (e.g., Promise<Result>)
• Effect race/cleanup: guard useEffect data fetches against out-of-order responses and post-unmount state updates — abort or ignore stale results (AbortController or a mounted flag), or use a server-state library (React Query/SWR) that cancels and dedupes. try-catch alone does not cover this

Format Rules

• Semicolon omission (follow Biome settings)
• Types in PascalCase, variables/functions in camelCase
• Imports use absolute paths (src/)

Clean Code Principles

• Delete unused code immediately
• Delete debug console.log()
• Delete commented-out code (retrieve from version control when needed)
• Comments explain "why" (not "what")

Error Handling

Absolute Rule: Every caught error must be logged with context and either re-thrown to Error Boundary, returned as a Result error variant, or displayed as user-facing error state.

Fail-Fast Principle: Fail quickly on errors to prevent continued processing in invalid states

catch (error) {
  logger.error('Processing failed', error)
  throw error // Handle with Error Boundary or higher layer
}

Result Type Pattern: Express errors with types for explicit handling

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }

// Example: Express error possibility with types
function parseUser(data: unknown): Result<User, ValidationError> {
  if (!isValid(data)) return { ok: false, error: new ValidationError() }
  return { ok: true, value: data as User }
}

Custom Error Classes

export class AppError extends Error {
  constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
    super(message)
    this.name = this.constructor.name
  }
}
// Purpose-specific: ValidationError(400), ApiError(502), NotFoundError(404)

Layer-Specific Error Handling (React)

• Error Boundary: Catch React component errors, display fallback UI
• Custom Hook: Detect business rule violations, propagate AppError as-is
• API Layer: Convert fetch errors to domain errors

Structured Logging and Sensitive Information Protection Redact sensitive fields (password, token, apiKey, secret, creditCard) before logging

Asynchronous Error Handling in React

• Error Boundary setup mandatory: Catch rendering errors
• Use try-catch with all async/await in event handlers
• Always log and re-throw errors or display error state

Refactoring Techniques

Basic Policy

• Small Steps: Maintain always-working state through gradual improvements
• Safe Changes: Minimize the scope of changes at once
• Behavior Guarantee: Ensure existing behavior remains unchanged while proceeding

Implementation Procedure: Understand Current State → Gradual Changes → Behavior Verification → Final Validation

Priority: Duplicate Code Removal > Large Function Division > Complex Conditional Branch Simplification > Type Safety Improvement

Performance Optimization

• Automatic memoization: when React Compiler is enabled, rely on it; reach for manual React.memo/useMemo/useCallback only as a profiler- or identity-justified escape hatch (a measured bottleneck, or stable reference identity for third-party APIs / effect dependencies)
• State Optimization: Minimize re-renders with proper state structure
• Lazy Loading: Use React.lazy and Suspense for code splitting
• Bundle Size: Monitor via the build script against the project's budget

Non-functional Requirements

• Browser Compatibility: Chrome/Firefox/Safari/Edge (latest 2 versions)
• Rendering Time: Within 5 seconds for major pages

AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection

Technical Anti-patterns (Red Flag Patterns)

Immediately stop and reconsider design when detecting the following patterns:

Code Quality Anti-patterns

1. Writing similar code 3 or more times - Violates Rule of Three
2. Multiple responsibilities mixed in a single file - Violates Single Responsibility Principle (SRP)
3. Defining same content in multiple files - Violates DRY principle
4. Making changes without checking dependencies - Potential for unexpected impacts
5. Disabling code with comments - Should use version control
6. Error suppression - Hiding problems creates technical debt
7. Bypassing safety mechanisms (type systems, validation, contracts) - Circumventing language's correctness guarantees

Design Anti-patterns

• "Make it work for now" thinking - Accumulation of technical debt
• Patchwork implementation - Unplanned additions to existing code
• Optimistic implementation of uncertain technology - Designing unknown elements assuming "it'll probably work"
• Symptomatic fixes - Surface-level fixes that don't solve root causes
• Unplanned large-scale changes - Lack of incremental approach

Fail-Fast Fallback Design Principles

Core Principle

Make all errors visible and traceable with full context. Prioritize primary code reliability over fallback implementations. Excessive fallback mechanisms mask errors and make debugging difficult.

Implementation Guidelines

Default Approach

• Propagate all errors explicitly unless a Design Doc specifies a fallback
• Make failures explicit: Errors should be visible and traceable
• Preserve error context: Include original error information when re-throwing

When Fallbacks Are Acceptable

• Only with explicit Design Doc approval: Document why fallback is necessary
• Business-critical continuity: When partial functionality is better than none
• Graceful degradation paths: Clearly defined degraded service levels

Layer Responsibilities

• Infrastructure Layer:

  • Always throw errors upward
  • No business logic decisions
  • Provide detailed error context

• Application Layer:

  • Make business-driven error handling decisions
  • Implement fallbacks only when specified in requirements
  • Log all fallback activations for monitoring

Error Masking Detection

Review Triggers (require design review):

• Writing 3rd error handler in the same feature
• Multiple error handling blocks in single function/method
• Nested error handling structures
• Error handlers that return default values without logging

Before Implementing Any Fallback:

1. Verify Design Doc explicitly defines this fallback
2. Document the business justification
3. Ensure error is logged with full context
4. Add monitoring/alerting for fallback activation

Implementation Pattern

AVOID: Silent fallback that hides errors
    <handle error>:
        return DEFAULT_VALUE  // Error hidden, debugging impossible

PREFERRED: Explicit failure with context
    <handle error>:
        log_error('Operation failed', context, error)
        <propagate error>  // Re-throw exception, return Error, return error tuple

Adaptation: Use language-appropriate error handling (exceptions, Result types, error tuples, etc.)

Rule of Three - Criteria for Code Duplication

How to handle duplicate code based on Martin Fowler's "Refactoring":

Criteria for Commonalization

Cases for Commonalization

• Business logic duplication
• Complex processing algorithms
• Areas likely requiring bulk changes
• Validation rules

Cases to Avoid Commonalization

• Accidental matches (coincidentally same code)
• Possibility of evolving in different directions
• Significant readability decrease from commonalization
• Simple helpers in test code

Common Failure Patterns and Avoidance Methods

Pattern 1: Error Fix Chain

Symptom: Fixing one error causes new errors Cause: Surface-level fixes without understanding root cause Avoidance: Identify root cause with 5 Whys before fixing

Pattern 2: Circumventing Correctness Guarantees

Symptom: Bypassing safety mechanisms (type systems, validation, contracts) Cause: Impulse to avoid correctness errors Avoidance: Use language-appropriate safety mechanisms (static checking, runtime validation, contracts, assertions)

Pattern 3: Implementation Without Sufficient Testing

Symptom: Many bugs after implementation Cause: Ignoring Red-Green-Refactor process Avoidance: Always start with failing tests

Pattern 4: Ignoring Technical Uncertainty

Symptom: Frequent unexpected errors when introducing new technology Cause: Assuming "it should work according to official documentation" without prior investigation Avoidance:

• Record certainty evaluation at the beginning of task files

  Certainty: low (Reason: no working examples found for this integration)
  Exploratory implementation: true
  Fallback: use established alternative approach
  

• For low certainty cases, create minimal verification code first

Pattern 5: Insufficient Existing Code Investigation

Symptom: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns Cause: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness Avoidance Methods:

• Before implementation, always search for similar functionality (using domain, responsibility, configuration patterns as keywords)
• Similar functionality found → Use that implementation (do not create new implementation)
• Similar functionality is technical debt → Create ADR improvement proposal before implementation
• No similar functionality exists → Implement new functionality following existing design philosophy
• Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc
• Reference representativeness check: When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting — nearby files alone are an insufficient basis

Debugging Techniques

1. Error Analysis Procedure

1. Read error message (first line) accurately
2. Focus on first and last of stack trace
3. Identify first line where your code appears

2. 5 Whys - Root Cause Analysis

Trace the failure through repeated "why" questions until the root cause is actionable.

3. Minimal Reproduction Code

To isolate problems, attempt reproduction with minimal code:

• Remove unrelated parts
• Replace external dependencies with mocks
• Create minimal configuration that reproduces problem

4. Debug Log Output

Include operation context, relevant input data, current state, and timestamp.

Quality Assurance Mechanism Awareness

Before executing quality checks, identify what quality mechanisms exist for the change area:

• Primary detection: inspect the change area's file types, project manifest, and configuration to identify applicable quality tools
  • Check CI pipeline definitions for checks that cover the affected paths
  • Check for domain-specific linter or validator configurations (e.g., schema validators, API spec validators, configuration file linters)
  • Check for domain-specific constraints in project configuration (naming rules, length limits, format requirements)
• Supplementary hint: IF task file specifies Quality Assurance Mechanisms → use them as additional hints for which domain-specific checks to look for
• Include discovered domain-specific checks alongside standard quality phases below

Quality Check Workflow

Universal quality assurance phases applicable to all languages:

Phase 1: Static Analysis

1. Code Style Checking: Verify adherence to style guidelines
2. Code Formatting: Ensure consistent formatting
3. Unused Code Detection: Identify dead code and unused imports/variables
4. Static Type Checking: Verify type correctness (for statically typed languages)
5. Static Analysis: Detect potential bugs, security issues, code smells

Phase 2: Build Verification

1. Compilation/Build: Verify code builds successfully (for compiled languages)
2. Dependency Resolution: Ensure all dependencies are available and compatible
3. Resource Validation: Check configuration files, assets are valid

Phase 3: Testing

1. Unit Tests: Run all unit tests
2. Integration Tests: Run integration tests
3. Test Coverage: Measure and verify coverage meets standards
4. E2E Tests: Run end-to-end tests

Phase 4: Final Quality Gate

All checks must pass before proceeding:

• Zero static analysis errors
• Build succeeds
• All tests pass
• Coverage meets project-configured threshold

Quality Check Pattern (Language-Agnostic)

Workflow:
1. Format check → 2. Lint/Style → 3. Static analysis →
4. Build/Compile → 5. Unit tests → 6. Coverage check →
7. Integration tests → 8. Final gate

Auto-fix capabilities (when available):
- Format auto-fix
- Lint auto-fix
- Dependency/import organization
- Simple code smell corrections

Situations Requiring Technical Decisions

Timing of Abstraction

• Extract patterns after writing concrete implementation 3 times
• Be conscious of YAGNI, implement only currently needed features
• Prioritize current simplicity over future extensibility

Performance vs Readability

• Prioritize readability unless profiling identifies a measurable bottleneck (e.g., response time exceeding SLA, memory exceeding allocation)
• Measure before optimizing
• Document reason with comments when optimizing

Granularity of Contracts and Interfaces

• Overly detailed contracts reduce maintainability
• Design interfaces where each method maps to a single domain operation and parameter types use domain vocabulary
• Use abstraction mechanisms to reduce duplication

Scope Expansion

• Apply implementation/edit instructions to the user's or task's specified scope. Escalate before expanding it.
• Treat explicit quantities and targets ("one", "this file", "only X") as boundaries
• Copy/move/mirror requests preserve content verbatim; edit content only when requested
• Port/translation requests preserve intent and behavior; adapt only what the destination context requires
• Before changing related files, symmetric locations, adjacent behavior, or adding helpful extras, escalate with the proposed expansion

Implementation Completeness Assurance

Impact Analysis: Mandatory 3-Stage Process

Complete these stages sequentially before any implementation:

1. Discovery - Identify all affected code:

• Implementation references (imports, calls, instantiations)
• Interface dependencies (contracts, types, data structures)
• Test coverage
• Configuration (build configs, env settings, feature flags)
• Documentation (comments, docs, diagrams)

2. Understanding - Analyze each discovered location:

• Role and purpose in the system
• Dependency direction (consumer or provider)
• Data flow (origin → transformations → destination)
• Coupling strength

3. Identification - Produce structured report:

## Impact Analysis
### Direct Impact
- [Unit]: [Reason and modification needed]

### Indirect Impact
- [System]: [Integration path → reason]

### Data Flow
[Source] → [Transformation] → [Consumer]

### Risk Assessment
- High: [Complex dependencies, fragile areas]
- Medium: [Moderate coupling, test gaps]
- Low: [Isolated, well-tested areas]

### Implementation Order
1. [Start with lowest risk or deepest dependency]
2. [...]

Critical: Do not implement until all 3 stages are documented

Unused Code Deletion

When unused code is detected:

• Will it be used in this work? Yes → Implement now | No → Delete now (Git preserves)
• Applies to: Code, tests, docs, configs, assets

Existing Code Modification

In use? No → Delete
       Yes → Working? No → Delete + Reimplement
                     Yes → Fix/Extend

Principle: Prefer clean implementation over patching broken code

Language-Agnostic Coding Principles

Core Philosophy

1. Maintainability over Speed: Prioritize long-term code health over initial development velocity
2. Simplicity First: Choose the simplest solution that meets requirements (YAGNI principle)
3. Minimum Surface for Required Coverage: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point.
4. Explicit over Implicit: Make intentions clear through code structure and naming
5. Delete over Comment: Remove unused code instead of commenting it out

Code Quality

Continuous Improvement

• Refactor related code within each change set — address style, naming, or structure issues in the files being modified
• Improve code structure incrementally
• Keep the codebase lean and focused
• Delete unused code immediately

Readability

• Use meaningful, descriptive names drawn from the problem domain
• Use full words in names; abbreviations are acceptable only when widely recognized in the domain
• Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)
• Extract magic numbers and strings into named constants
• Keep code self-documenting where possible

Function Design

Parameter Management

• Recommended: 0-2 parameters per function
• For 3+ parameters: Use objects, structs, or dictionaries to group related parameters
• Example (conceptual):

  // Instead of: createUser(name, email, age, city, country)
  // Use: createUser(userData)
  

Single Responsibility

• Each function should do one thing well
• Keep functions small and focused (typically < 50 lines)
• Extract complex logic into separate, well-named functions
• Functions should have a single level of abstraction

Function Organization

• Pure functions when possible (no side effects)
• Separate data transformation from side effects
• Use early returns to reduce nesting
• Keep nesting to a maximum of 3 levels; use early returns or extracted functions to flatten deeper nesting

Error Handling

Error Management Principles

• Always handle errors: Log with context or propagate explicitly
• Log appropriately: Include context for debugging
• Protect sensitive data: Mask or exclude passwords, tokens, PII from logs
• Fail fast: Detect and report errors as early as possible

Error Propagation

• Use language-appropriate error handling mechanisms
• Propagate errors to appropriate handling levels
• Provide meaningful error messages
• Include error context when re-throwing

Dependency Management

Loose Coupling via Parameterized Dependencies

• Inject external dependencies as parameters (constructor injection for classes, function parameters for procedural/functional code)
• Depend on abstractions, not concrete implementations
• Minimize inter-module dependencies
• Facilitate testing through mockable dependencies

Reference Representativeness

Verifying References Before Adoption

When adopting patterns, APIs, or dependencies from existing code:

• IF referencing only 2-3 nearby files → THEN confirm the pattern is representative by checking usage across the repository before adopting
• IF multiple approaches coexist in the repository → THEN identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient
• IF adopting an external dependency (library, plugin, SDK) → THEN verify repository-wide usage distribution for the same dependency; if the appropriate version cannot be determined from repository state alone, escalate
• IF following an existing pattern → THEN state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update)

Principle

Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model.

Performance Considerations

Optimization Approach

• Measure first: Profile before optimizing
• Focus on algorithms: Algorithmic complexity > micro-optimizations
• Use appropriate data structures: Choose based on access patterns
• Resource management: Handle memory, connections, and files properly

When to Optimize

• After identifying actual bottlenecks through profiling
• When performance issues are measurable
• Optimize only after measurable bottlenecks are identified, not during initial development

Code Organization

Structural Principles

• Group related functionality: Keep related code together
• Separate concerns: Domain logic, data access, presentation
• Consistent naming: Follow project conventions
• Module cohesion: High cohesion within modules, low coupling between

File Organization

• One primary responsibility per file
• Logical grouping of related functions/classes
• Clear folder structure reflecting architecture
• Avoid "god files" (files > 500 lines)

Commenting Principles

Default: code first

Names, types, and structure are the primary medium. A comment earns its place only by carrying information the code itself cannot express. When in doubt, improve the name instead of adding a comment.

The test for every comment

A comment is justified only if it answers one of these:

• Why: reasoning, trade-off, or constraint behind a non-obvious decision
• Limitation / edge case: a boundary a reader cannot infer from the code
• Public API contract: behavior, inputs, outputs of an exported interface

One comment per decision. If a comment restates what the names and control flow already show, delete it and rename instead.

Comment Scope

• Comment the why, limits, and public contracts (per the test above); let names and structure carry everything else, including the "how"
• Record historical context in version control commit messages, not in comments
• Delete commented-out code (retrieve from git history when needed)

Comment Quality

• Write comments that remain accurate regardless of future code changes; avoid references to dates, versions, or temporary state
• Update comments when changing code
• Use proper grammar and formatting
• Write for future maintainers

Refactoring Approach

Safe Refactoring

• Small steps: Make one change at a time
• Maintain working state: Keep tests passing
• Verify behavior: Run tests after each change
• Incremental improvement: Don't aim for perfection immediately

Refactoring Triggers

• Code duplication (DRY principle)
• Functions > 50 lines
• Complex conditional logic
• Unclear naming or structure

Testing Considerations

Testability

• Write testable code from the start
• Avoid hidden dependencies
• Keep side effects explicit
• Design for parameterized dependencies

Test-Driven Development

• Write tests before implementation when appropriate
• Keep tests simple and focused
• Test behavior, not implementation
• Maintain test quality equal to production code

Security Principles

Secure Defaults

• Store credentials and secrets through environment variables or dedicated secret managers
• Use parameterized queries (prepared statements) for all database access
• Use established cryptographic libraries provided by the language or framework
• Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators
• Encrypt sensitive data at rest and in transit using standard protocols

Input and Output Boundaries

• Validate all external input at system entry points for expected format, type, and length
• Encode output appropriately for its rendering context (HTML, SQL, shell, URL)
• Return only information necessary for the caller in error responses; log detailed diagnostics server-side

Access Control

• Apply authentication to all entry points that handle user data or trigger state changes
• Verify authorization for each resource access, not only at the entry point
• Grant only the permissions required for the operation (files, database connections, API scopes)

Knowledge Cutoff Supplement (2026-03)

• OWASP Top 10:2025 shifted from symptoms to root causes; added "Software Supply Chain Failures" (A03) and "Mishandling of Exceptional Conditions" (A10)
• Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets
• OpenSSF published "Security-Focused Guide for AI Code Assistant Instructions" — recommends language-specific, actionable constraints over generic advice
• For detailed detection patterns, see references/security-checks.md

Documentation

Code Documentation

• Document public APIs and interfaces
• Include usage examples for complex functionality
• Maintain README files for modules
• Update documentation in the same commit that changes the corresponding behavior

Architecture Documentation

• Document high-level design decisions
• Explain integration points
• Clarify data flows and boundaries
• Record trade-offs and alternatives considered

Version Control Practices

Commit Practices

• Make atomic, focused commits
• Write clear, descriptive commit messages
• Commit working code (passes tests)
• Commit only production-ready code; store secrets in environment variables or secret managers

Code Review Readiness

• Self-review before requesting review
• Keep changes focused and reviewable
• Provide context in pull request descriptions
• Respond to feedback constructively

Language-Specific Adaptations

While these principles are language-agnostic, adapt them to your specific programming language:

• Static typing: Use strong types when available
• Dynamic typing: Add runtime validation
• OOP languages: Apply SOLID principles
• Functional languages: Prefer pure functions and immutability
• Concurrency: Follow language-specific patterns for thread safety

Documentation Creation Criteria

Templates

• prd-template.md - Product Requirements Document template
• adr-template.md - Architecture Decision Record template
• ui-spec-template.md - UI Specification template (frontend/fullstack features)
• design-template.md - Technical Design Document template
• plan-template.md - Work Plan template
• task-template.md - Task file template for implementation tasks

Creation Decision Matrix

ADR Creation Conditions (Required if Any Apply)

1. Contract System Changes

• Adding nested contracts with 3+ levels: Contract A { Contract B { Contract C { field: T } } }
  • Rationale: Deep nesting has high complexity and wide impact scope
• Changing/deleting contracts used in 3+ locations
  • Rationale: Multiple location impacts require careful consideration
• Contract responsibility changes (e.g., DTO→Entity, Request→Domain)
  • Rationale: Conceptual model changes affect design philosophy

2. Data Flow Changes

• Storage location changes (DB→File, Memory→Cache)
• Processing order changes with 3+ steps
  • Example: "Input→Validation→Save" to "Input→Save→Async Validation"
• Data passing method changes (parameter passing→shared state, direct reference→event-based communication)

3. Architecture Changes

• Layer addition, responsibility changes, component relocation

4. External Dependency Changes

• Library/framework/external API introduction or replacement

5. Complex Implementation Logic (Regardless of Scale)

• Managing 3+ states
• Coordinating 5+ asynchronous processes

Detailed Document Definitions

PRD (Product Requirements Document)

Purpose: Define business requirements and user value

Includes:

• Business requirements and user value
• Success metrics and KPIs (each metric specifies a numeric target and measurement method)
• User stories and use cases
• MoSCoW prioritization (Must/Should/Could/Won't)
• Acceptance criteria with sequential IDs (AC-001, AC-002, ...) for downstream traceability
• MVP and Future phase separation
• User journey diagram (required)
• Scope boundary diagram (required)

Scope: Business requirements, user value, success metrics, user stories, and prioritization only. Implementation details belong in Design Doc, technical selection rationale in ADR, phases and task breakdown in Work Plan.

ADR (Architecture Decision Record)

Purpose: Record technical decision rationale and background

Includes:

• Decision (what was selected)
• Rationale (why that selection was made)
• Option comparison (minimum 3 options) and trade-offs
• Architecture impact
• Principled implementation guidelines (e.g., "Use dependency injection")

Scope: Decision, rationale, option comparison, architecture impact, and principled guidelines only. Implementation procedures and code examples belong in Design Doc, schedule and resource assignments in Work Plan.

UI Specification

Purpose: Define UI structure, screen transitions, component decomposition, and interaction design for frontend features

Includes:

• Screen list and transition conditions
• Component decomposition with state x display matrix (default/loading/empty/error/partial)
• Interaction definitions linked to PRD acceptance criteria (EARS format)
• Prototype management (code-based prototypes as attachments, not source of truth)
• AC traceability from PRD to screens/components
• Existing component reuse map and design tokens
• Visual acceptance criteria (golden states, layout constraints)
• Accessibility requirements (keyboard, screen reader, contrast)

Scope: Screen structure, transitions, component decomposition, interaction design, and visual acceptance criteria only. Technical implementation and API contracts belong in Design Doc, test implementation in test skeleton generation output, schedule in Work Plan.

Required Structural Elements:

• At least one component with state x display matrix and interaction table
• AC traceability table mapping PRD ACs to screens/states
• Screen list with transition conditions
• Existing component reuse map (reuse/extend/new decisions)

Prototype Code Handling:

• Prototype code provided by user is placed in docs/ui-spec/assets/{feature-name}/
• Prototype is an attachment to UI Spec, never the source of truth
• UI Spec + Design Doc are the canonical specifications

Design Document

Purpose: Define technical implementation methods in detail

Includes:

• Existing codebase analysis (required)
  • Implementation path mapping (both existing and new)
  • Integration point clarification (connection points with existing code even for new implementations)
• Technical implementation approach (vertical/horizontal/hybrid)
• Technical dependencies and implementation constraints (required implementation order)
• Interface and contract definitions
• Data flow and component design
• Acceptance criteria (each criterion specifies a verifiable condition with pass/fail threshold)
• Change impact map (clearly specify direct impact/indirect impact/no ripple effect)
• Complete enumeration of integration points
• Data contract clarification
• Agreement checklist (agreements with stakeholders)
• Code inspection evidence (inspected files/functions during investigation)
• Field propagation map (when fields cross component boundaries)
• Data representation decision (when introducing new structures)
• Applicable standards (explicit/implicit classification)
• Prerequisite ADRs (including common ADRs)
• Verification Strategy (required)
  • Correctness proof method (what "correct" means for this change, how it's verified, when)
  • Early verification point (first target to prove the approach works, success criteria, failure response)

Required Structural Elements:

Change Impact Map:
  Change Target: [Component/Feature]
  Direct Impact: [Files/Functions]
  Indirect Impact: [Data format/Processing time]
  No Ripple Effect: [Unaffected features]

Interface Change Matrix:
  Existing: [Function/method/operation name]
  New: [Function/method/operation name]
  Conversion Required: [Yes/No]
  Compatibility Method: [Approach]

Scope: Technical implementation methods, interfaces, data flow, acceptance criteria, and verification strategy only. Technology selection rationale belongs in ADR, schedule and assignments in Work Plan.

Work Plan

Purpose: Implementation task management and progress tracking

Includes:

• Task breakdown and dependencies (maximum 2 levels)
• Schedule and duration estimates
• Include test skeleton file paths produced for this work plan (integration and E2E)
• Verification Strategy summary (extracted from Design Doc)
• Final Quality Assurance Phase (required)
• Progress records (checkbox format)

Scope: Task breakdown, dependencies, schedule, verification strategy summary, and progress tracking only. Technical rationale belongs in ADR, design details in Design Doc.

Phase Division Criteria (adapt to implementation approach from Design Doc):

When Vertical Slice selected:

• Each phase = one value unit (feature, component, or migration target)
• Each phase includes its own implementation + verification per Verification Strategy

When Horizontal Slice selected:

1. Phase 1: Foundation Implementation - Contract definitions, interfaces/signatures, test preparation
2. Phase 2: Core Feature Implementation - Business logic, unit tests
3. Phase 3: Integration Implementation - External connections, presentation layer

When Hybrid selected:

• Combine vertical and horizontal as defined in Design Doc implementation approach

All approaches: Final phase is always Quality Assurance (acceptance criteria achievement, all tests passing, quality checks). Each phase's verification method follows Verification Strategy from Design Doc.

Three Elements of Task Completion Definition:

1. Implementation Complete: Code is functional
2. Quality Complete: Tests, static checks, linting pass
3. Integration Complete: Verified connection with other components

Creation Process

1. Problem Analysis: Change scale assessment, ADR condition check
   • Identify explicit and implicit project standards before investigation
2. ADR Option Consideration (ADR only): Compare 3+ options, specify trade-offs
3. Creation: Use templates, include measurable conditions
4. Approval: "Accepted" after review enables implementation

Storage Locations

*Note: Work plans are excluded by .gitignore

ADR Status

Proposed → Accepted → Deprecated/Superseded/Rejected

AI Automation Rules

• 6+ files: Suggest ADR creation
• Contract/data flow change detected: ADR mandatory
• Check existing ADRs before implementation

Diagram Requirements

Required diagrams for each document (using mermaid notation):

Common ADR Relationships

1. At creation: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
2. When missing: Consider creating necessary common ADRs
3. Design Doc: Specify common ADRs in "Prerequisite ADRs" section
4. Compliance check: Verify design aligns with common ADR decisions

External Resource Context

Purpose

AI agents understand the codebase but not the external resources surrounding it. This skill captures, in a deterministic location, the access methods to resources outside the repository so downstream work (design, planning, implementation, review) can reach them without re-asking the user.

Resources covered: design origin (where the canonical visual specification lives), design system (component library and tokens), guidelines (usage docs, accessibility rules), visual verification environment (how to confirm rendering), database schema source, migration history, secret store location, API schema source (OpenAPI / proto / GraphQL SDL), mock environment, IaC source, environment configuration.

Scope Boundaries

In scope: hearing protocol, storage location, single-source-of-truth ownership rule, reference protocol for downstream consumers.

Out of scope: enforcing that captured resources are correct or current — verification belongs to the agent that consumes the resource. Generating the resources themselves (e.g., creating a DESIGN.md from scratch).

Storage Locations (Two-Tier)

Single Source of Truth Rule

The project tier owns environment facts. Feature-tier sections list only feature-specific identifiers (node id within the design source, specific endpoint path within the API, specific IaC module name) and reference project-tier entries by label; URLs, MCP names, and access commands remain in the project-tier file. When the environment changes, only the project-tier file is updated.

Example feature-tier entry uses the table format defined in references/template.md: a row with the project-tier label in the first column and the feature-specific identifier in the second column.

Hearing Protocol

When to Hear

Domain Routing

Load the domain reference matching the current task:

Each domain reference defines the axes and the question template.

Two-Phase Hearing

1. Structured hearing — for each axis defined in the domain reference, present the user with AskUserQuestion using the choices listed there (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command).

2. Self-declaration — after the structured axes, present a single AskUserQuestion: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If the user describes additional resources, append them to the storage file under an "Additional resources" subsection.

The two phases are sequential. Self-declaration runs even if the user answered "Not applicable" to every structured axis.

Storage Protocol

After hearing completes:

1. Build the project-tier content from the answers. Use references/template.md as the structure.
2. Write to docs/project-context/external-resources.md. Create the directory if absent.
3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's ## External Resources Used section with the feature-tier subset (label references + feature-specific identifiers only).
4. Report the file paths back to the calling workflow.

Reference Protocol (For Downstream Consumers)

Agents that load this skill consult resources in this order:

1. Read docs/project-context/external-resources.md first (if present) to learn what is available and how to access it.
2. Read the target UI Spec or Design Doc's ## External Resources Used section for feature-specific identifiers.
3. Use the access method declared in the project tier (e.g., the named MCP, the URL, the file path) to fetch the actual resource content.

Agents that only need to consult the saved file as input data (not actively hear) can read it directly without loading this skill — frontmatter declaration is reserved for agents that may need to trigger hearing or interpret the protocol semantics.

Output Format

The project-tier file follows the structure in references/template.md. The project-tier file's heading levels and section names are fixed so downstream agents can locate sections deterministically.

For feature-tier sections inside UI Spec or Design Doc, the heading text "External Resources Used" is fixed; the heading level matches the parent document's natural structure (h2 in UI Spec where it is a sibling of other top-level sections, h3 in Design Doc where it sits under Background and Context).

Quality Checklist

• Each axis answered has both a presence indicator and an access method, or is marked "Not applicable"
• Self-declaration phase ran even when all structured axes were "Not applicable"
• Project-tier file does not contain feature-specific identifiers
• Feature-tier sections reference project-tier entries by label, not by duplicating URLs / MCP names
• When the project file already existed, the update decision (no / yes-full / yes-diff-only) was confirmed before any write

References

• references/frontend.md — Frontend domain axes
• references/backend.md — Backend domain axes
• references/api.md — API contract domain axes
• references/infra.md — Infrastructure domain axes
• references/template.md — Project-tier and feature-tier structure templates

AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend)

Technical Anti-patterns (Red Flag Patterns)

Immediately stop and reconsider design when detecting the following patterns:

Code Quality Anti-patterns

1. Writing similar code 3 or more times - Violates Rule of Three
2. Multiple responsibilities mixed in a single component - Violates Single Responsibility Principle (SRP)
3. Defining same content in multiple components - Violates DRY principle
4. Making changes without checking dependencies - Potential for unexpected impacts
5. Disabling code with comments - Should use version control
6. Error suppression - Hiding problems creates technical debt
7. Excessive use of type assertions (as) - Abandoning type safety
8. Prop drilling through 3+ levels - Should use Context API or state management
9. Massive components (300+ lines) - Split into smaller components

Design Anti-patterns

• "Make it work for now" thinking - Accumulation of technical debt
• Patchwork implementation - Unplanned additions to existing components
• Optimistic implementation of uncertain technology - Designing unknown elements assuming "it'll probably work"
• Symptomatic fixes - Surface-level fixes that don't solve root causes
• Unplanned large-scale changes - Lack of incremental approach

Fallback Design Principles

Core Principle: Fail-Fast

Design philosophy that prioritizes improving primary code reliability over fallback implementations.

Criteria for Fallback Implementation

• Fallback rule: Implement fallbacks only when explicitly defined in Design Doc
• Layer Responsibilities:
  • Component Layer: Use Error Boundary for error handling
  • Hook Layer: Implement decisions based on business requirements

Detection of Excessive Fallbacks

• Require design review when writing the 3rd catch statement in the same feature
• Verify Design Doc definition before implementing fallbacks
• Properly log errors and make failures explicit

Rule of Three - Criteria for Code Duplication

How to handle duplicate code based on Martin Fowler's "Refactoring":

Criteria for Commonalization

Cases for Commonalization

• Business logic duplication
• Complex processing algorithms
• Component patterns (form fields, cards, etc.)
• Custom hooks
• Validation rules

Cases to Avoid Commonalization

• Accidental matches (coincidentally same code)
• Possibility of evolving in different directions
• Significant readability decrease from commonalization
• Simple helpers in test code

Implementation Example

// 1st-2nd occurrence: keep separate, no commonalization yet
function UserEmailInput() { /* ... */ }
function ContactEmailInput() { /* ... */ }

// Commonalize on 3rd occurrence
function EmailInput({ context }: { context: 'user' | 'contact' | 'admin' }) { /* ... */ }

Common Failure Patterns and Avoidance Methods

Pattern 1: Error Fix Chain

Symptom: Fixing one error causes new errors Cause: Surface-level fixes without understanding root cause Avoidance: Identify root cause with 5 Whys before fixing

Pattern 2: Abandoning Type Safety

Symptom: Excessive use of any type or as Cause: Impulse to avoid type errors Avoidance: Handle safely with unknown type and type guards

Pattern 3: Implementation Without Sufficient Testing

Symptom: Many bugs after implementation Cause: Ignoring Red-Green-Refactor process Avoidance: Always start with failing tests

Pattern 4: Ignoring Technical Uncertainty

Symptom: Frequent unexpected errors when introducing new technology Cause: Assuming "it should work according to official documentation" without prior investigation Avoidance:

• Record certainty evaluation at the beginning of task files

  Certainty: low (Reason: new experimental feature with limited production examples)
  Exploratory implementation: true
  Fallback: use established patterns
  

• For low certainty cases, create minimal verification code first

Pattern 5: Insufficient Existing Code Investigation

Symptom: Duplicate implementations, architecture inconsistency, integration failures Cause: Insufficient understanding of existing code before implementation Avoidance Methods:

• Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords)
• Similar functionality found → Use that implementation (do not create new implementation)
• Similar functionality is technical debt → Create ADR improvement proposal before implementation
• No similar functionality exists → Implement new functionality following existing design philosophy
• Record all decisions and rationale in "Existing Codebase Analysis" section of Design Doc

Debugging Techniques

1. Error Analysis Procedure

1. Read error message (first line) accurately
2. Focus on first and last of stack trace
3. Identify first line where your code appears
4. Check React DevTools for component hierarchy

2. 5 Whys - Root Cause Analysis

Symptom: Component not rendering
Why1: Props are undefined → Why2: Parent component didn't pass props
Why3: Parent using old prop names → Why4: Component interface was updated
Why5: No update to parent after refactoring
Root cause: Incomplete refactoring, missing call-site updates

3. Minimal Reproduction Code

To isolate problems, attempt reproduction with minimal code:

• Remove unrelated components
• Replace API calls with mocks
• Create minimal configuration that reproduces problem
• Use React DevTools to inspect component tree

4. Debug Log Output (temporary)

Add structured debug logs to isolate the issue, then remove them before commit (per "Delete debug console.log()" in typescript-rules):

console.log('DEBUG:', {
  context: 'user-form-submission',
  props: { email, name },
  state: currentState,
  timestamp: new Date().toISOString()
})

Quality Check Workflow

Read package.json scripts and run them with the project's package manager (packageManager field). Map the project's actual script names to the phases below — do not assume fixed names.

Phases (run in order)

1. Lint/format — the project's formatter + linter (e.g., Biome, or ESLint + Prettier)
2. Type check — type check without emit
3. Build — production build
4. Test — unit/integration tests
5. Coverage — coverage run when the task added or changed behavior

Troubleshooting

• Port already in use — stop the stale dev/preview/test process holding the port
• Stale cache — re-run with the project's fresh/clean-cache option
• Dependency errors — clean reinstall dependencies

Situations Requiring Technical Decisions

Timing of Abstraction

• Extract patterns after writing concrete implementation 3 times
• Be conscious of YAGNI, implement only currently needed features
• Prioritize current simplicity over future extensibility

Performance vs Readability

• Prioritize readability unless React DevTools Profiler identifies a measurable bottleneck (e.g., render time exceeding 16ms, unnecessary re-renders)
• Measure before optimizing with React DevTools Profiler
• Document reason with comments when optimizing

Granularity of Component/Type Definitions

• Overly detailed components/types reduce maintainability
• Design components that appropriately express UI patterns
• Use composition over inheritance

Implementation Completeness Assurance

Required Procedure for Impact Analysis

Completion Criteria: Complete all 3 stages

1. Discovery

Grep -n "ComponentName\|hookName" -o content
Grep -n "importedFunction" -o content
Grep -n "propsType\|StateType" -o content

2. Understanding

Mandatory: Read all discovered files and include necessary parts in context:

• Caller's purpose and context
• Component hierarchy
• Data flow: Props → State → Event handlers → Callbacks

3. Identification

Structured impact report (mandatory):

## Impact Analysis
### Direct Impact: ComponentA, ComponentB (with reasons)
### Indirect Impact: FeatureX, PageY (with integration paths)
### Processing Flow: Props → Render → Events → Callbacks

Important: Execute all 3 stages to completion

Unused Code Deletion Rule

When unused code is detected → Will it be used?

• Yes → Implement immediately (no deferral allowed)
• No → Delete immediately (remains in Git history)

Target: Components, hooks, utilities, documentation, configuration files

Existing Code Deletion Decision Flow

In use? No → Delete immediately (remains in Git history)
       Yes → Working? No → Delete + Reimplement
                     Yes → Fix

Implementation Strategy Selection Framework (Meta-cognitive Approach)

Meta-cognitive Strategy Selection Process

Phase 1: Comprehensive Current State Analysis

Core Question: "What does the existing implementation look like?"

Analysis Framework

Architecture Analysis: Responsibility separation, data flow, dependencies, technical debt
Implementation Quality Assessment: Code quality, test coverage, performance, security
Historical Context Understanding: Current form rationale, past decision validity, constraint changes, requirement evolution

Meta-cognitive Question List

• What is the true responsibility of this implementation?
• Which parts are business essence and which derive from technical constraints?
• What dependencies or implicit preconditions are unclear from the code?
• What benefits and constraints does the current design bring?

Phase 2: Strategy Exploration and Creation

Core Question: "When determining before → after, what implementation patterns or strategies should be referenced?"

Strategy Discovery Process

Research and Exploration: Tech stack examples (WebSearch), similar projects, OSS references, literature/blogs
Creative Thinking: Strategy combinations, constraint-based design, phase division, extension point design

Reference Strategy Patterns (Creative Combinations Encouraged)

Legacy Handling Strategies:

• Strangler Pattern: Gradual migration through phased replacement
• Facade Pattern: Complexity hiding through unified interface
• Adapter Pattern: Bridge with existing systems

New Development Strategies:

• Feature-driven Development: Vertical implementation prioritizing user value
• Foundation-driven Development: Foundation-first construction prioritizing stability
• Risk-driven Development: Prioritize addressing maximum risk elements

Integration/Migration Strategies:

• Proxy Pattern: Transparent feature extension
• Decorator Pattern: Phased enhancement of existing features
• Bridge Pattern: Flexibility through abstraction

Important: The optimal solution is discovered through creative thinking according to each project's context.

Phase 3: Risk Assessment and Control

Core Question: "What risks arise when applying this to existing implementation, and what's the best way to control them?"

Risk Analysis Matrix

Technical Risks: System impact, data consistency, performance degradation, integration complexity
Operational Risks: Service availability, deployment downtime, process changes, rollback procedures
Project Risks: Schedule delays, learning costs, quality achievement, team coordination

Risk Control Strategies

Preventive Measures: Phased migration, parallel operation verification, integration/regression tests, monitoring setup
Incident Response: Rollback procedures, log/metrics preparation, communication system, service continuation procedures

Phase 4: Constraint Compatibility Verification

Core Question: "What are this project's constraints?"

Constraint Checklist

Technical Constraints: Library compatibility, resource capacity, mandatory requirements, numerical targets
Temporal Constraints: Deadlines/priorities, dependencies, milestones, learning periods
Resource Constraints: Team/skills, work hours/systems, budget, external contracts
Business Constraints: Market launch timing, customer impact, regulatory compliance

Phase 5: Implementation Approach Decision

Select optimal solution from basic implementation approaches (creative combinations encouraged):

Vertical Slice (Feature-driven)

Characteristics: Vertical implementation across all layers by feature unit Application Conditions: Features share fewer than 2 data models, each feature is independently deliverable, changes touch 3+ architecture layers Verification Method: End-user value delivery at each feature completion

Horizontal Slice (Foundation-driven)

Characteristics: Phased construction by architecture layer Application Conditions: 3+ features depend on a common foundation layer, foundation changes require stability verification before consumers can proceed Verification Method: Integrated operation verification when all foundation layers complete

Hybrid (Creative Combination)

Characteristics: Flexible combination according to project characteristics Application Conditions: Unclear requirements, need to change approach per phase, transition from prototyping to full implementation Verification Method: Verify at appropriate L1/L2/L3 levels according to each phase's goals

Phase 6: Decision Rationale Documentation

Design Doc Documentation: Record in the Design Doc's implementation approach section:

1. Selected strategy name and characteristics
2. Alternatives considered and reason for rejection
3. Risk mitigation plan (from Phase 3)
4. Constraint compliance summary (from Phase 4)
5. Verification level (L1/L2/L3) and integration point definition

Verification Level Definitions

Priority for completion verification of each task:

• L1: Functional Operation Verification - Operates as end-user feature (e.g., search executable)
• L2: Test Operation Verification - New tests added and passing
• L3: Build Success Verification - Code builds/runs without errors

Priority: L1 > L2 > L3 in order of verifiability importance

Integration Point Definitions

Define integration points according to selected strategy:

• Strangler-based: When switching between old and new systems for each feature
• Feature-driven: When users can actually use the feature
• Foundation-driven: When all architecture layers are ready and E2E tests pass
• Hybrid: When individual goals defined for each phase are achieved

Quality Checks

1. Verify at least one strategy combination beyond listed patterns was considered
2. Confirm Phase 1 analysis framework is complete before selecting strategy
3. Confirm Phase 3 risk analysis matrix is populated before implementation starts
4. Confirm Phase 4 constraint checklist is reviewed before strategy decision
5. Confirm Phase 6 documentation template is filled with selection rationale

Guidelines for Meta-cognitive Execution

1. Leverage Known Patterns: Use as starting point, explore creative combinations
2. Active WebSearch Use: Research implementation examples from similar tech stacks
3. Apply 5 Whys: Pursue root causes to grasp essence
4. Multi-perspective Evaluation: Comprehensively evaluate from each Phase 1-4 perspective

Integration and E2E Testing Principles

References

E2E test design: See references/e2e-design.md for UI Spec-driven E2E test candidate selection and browser test architecture. The reference uses Playwright as the default browser harness; substitute the project's standard when different.

Test Type Definition and Limits

Lane selection (E2E only):

• Default lane for user-facing UI journeys is fixture-e2e — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup
• Add service-integration-e2e only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely

The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa.

Behavior-First Principle

Include (High ROI)

• Business logic correctness (calculations, state transitions, data transformations)
• Data integrity and persistence behavior
• User-visible functionality completeness
• Error handling behavior (what user sees/experiences)

Redirect to Other Test Types

• External service connections → Verify via contract/interface tests
• Performance metrics → Verify via dedicated load testing
• Implementation details → Verify observable behavior instead
• UI layout specifics → Verify information availability instead

Principle: Test = User-observable behavior verifiable in isolated CI environment

ROI Calculation

ROI is used to rank candidates within the same test type (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently.

ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection
              (range: 0–120)

Higher ROI Score = higher priority within its test type. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores.

ROI Thresholds by Lane

The two E2E lanes have very different ownership costs and use independent thresholds.

Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Below-floor candidates beyond the reserved slot are not emitted, leaving budget intentionally unfilled rather than padding with low-value tests.

ROI Calculation Examples

Multi-Step User Journey Definition

A feature qualifies as containing a multi-step user journey when ALL of the following are true:

1. 2+ distinct interaction boundaries are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type:
   • Web: distinct routes/pages
   • Mobile native: distinct screens/views
   • CLI: distinct command invocations or interactive prompts
   • API: distinct API calls forming a transaction (e.g., create → confirm → finalize)
2. State carries across steps — data produced or actions taken in one step affect what the next step accepts or displays
3. The journey has a completion point — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow)

User-Facing vs Service-Internal Journeys

Multi-step journeys are classified for reserved-slot eligibility:

This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above.

Use this definition when evaluating E2E test candidates and E2E gap detection.

Test Skeleton Specification

Required Comment Patterns

Each test MUST include the following annotations:

AC: [Original acceptance criteria text]
Behavior: [Trigger] → [Process] → [Observable Result]
@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e
@lane: integration | fixture-e2e | service-integration-e2e
@dependency: none | [component names] | full-system
@complexity: low | medium | high
ROI: [score]

@lane selection rule:

• integration — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language)
• fixture-e2e — Browser-level UI verification with mocked backend / fixture-driven state
• service-integration-e2e — Browser-level or end-to-end verification against running local services or stubs

Use the project's comment syntax to wrap these annotations (e.g., // for C-family, # for Python/Ruby/Shell).

Verification Items (Optional)

When verification points need explicit enumeration:

Verification items:
- [Item 1]
- [Item 2]

EARS Format Mapping

Test File Naming Convention

• Integration tests: *.int.test.* or *.integration.test.*
• fixture-e2e tests: *.fixture.e2e.test.* (or organize under tests/e2e/fixture/)
• service-integration-e2e tests: *.service.e2e.test.* (or organize under tests/e2e/service/)

The test runner or framework in the project determines the appropriate file extension. Repos that already use a single *.e2e.test.* convention may keep it as long as each file declares @lane: in its header — the lane annotation is the source of truth for routing and budget accounting.

Review Criteria

Skeleton and Implementation Consistency

Implementation Quality

Quality Standards

Required

• Each test verifies one behavior
• Clear AAA (Arrange-Act-Assert) structure
• No test interdependencies
• Deterministic execution

LLM-Friendly Context

The goal is stable downstream execution: the next agent should know what to read, what to do, what counts as success, and when to stop or escalate.

Core Rules

1. Use positive, executable instructions

   • State what the next agent should do.
   • Convert quality policies into positive criteria.
   • Example: "Preserve existing public API behavior across the documented compatibility cases."

2. Make vague instructions concrete

   • Replace subjective terms with observable conditions, paths, commands, schemas, examples, or decision rules.
   • Terms that often need clarification when they leave a decision to the next agent: appropriate, proper, related, existing behavior, optional, as needed, if needed, per convention, unresolved alternatives, TBD, placeholder.

3. Specify output shape

   • Define required sections, fields, table columns, JSON keys, or checklist items.
   • For handoffs, include paths to produced artifacts and the exact status fields the caller must inspect.

4. Provide necessary context

   • Include the purpose, source artifacts, hard constraints, accepted decisions, and unresolved conditions.
   • Prefer concrete file paths and section hints over broad module names.

5. Decompose complex work into verifiable steps

   • Split work with 3+ objectives or sequential dependencies into ordered steps.
   • Each step needs a checkpoint: what evidence proves it is complete.

6. Permit uncertainty explicitly

   • If the source material is missing, contradictory, or not verifiable, state the uncertainty and the required escalation.
   • Record unknown business, product, security, or compatibility decisions as blocking unresolved items with the input needed to resolve them.

7. Keep constraints proportionate

   • Add only constraints that reduce ambiguity or preserve a real requirement.
   • Keep simple downstream tasks lightweight when the target action, context, and success criteria are already clear.

Rewrite Patterns

Use these rewrites before treating a prompt, handoff, or artifact as complete.

Handoff Checklist

Before sending a prompt or artifact to another agent, verify:

• The target action is explicit.
• Required input paths and source artifacts are named.
• Accepted decisions and constraints are stated once, without alternate wording.
• Output format or expected status fields are specified.
• Success criteria are observable.
• Ambiguous expressions have been rewritten or marked as unresolved.
• The next agent can complete its scope with explicit choices, decision rules, or blocking unresolved items.

Generated Artifact Checklist

Before writing or finalizing a generated document:

• Each requirement, claim, task, test skeleton, or review finding has enough source context to trace why it exists.
• Every executable instruction names the target, action, and expected result.
• Verification steps say what to run or observe and what result proves success.
• If an artifact is derived from another artifact, copied decisions stay consistent in wording and meaning.
• If downstream work is blocked by missing information, the artifact records the missing input and escalation condition.

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Context: Diagnosis flow to identify root cause and present solutions

Target problem: $ARGUMENTS

Orchestrator Definition

Core Identity: "I am not a worker. I am an orchestrator."

Execution Method:

• Investigation → performed by investigator
• Verification → performed by verifier
• Solution derivation → performed by solver

Orchestrator invokes sub-agents and passes structured JSON between them.

Task Registration: Register execution steps using TaskCreate and proceed systematically. Update status using TaskUpdate.

Step 0: Problem Structuring (Before investigator invocation)

0.1 Problem Type Determination

If uncertain, ask the user whether any changes were made right before the problem occurred.

0.2 Information Supplementation for Change Failures

If the following are unclear, ask with AskUserQuestion before proceeding:

• What was changed (cause change)
• What broke (affected area)
• Relationship between both (shared components, etc.)

0.3 Problem Essence Understanding

Invoke rule-advisor via Agent tool:

subagent_type: rule-advisor
description: "Problem essence analysis"
prompt: Identify the essence and required rules for this problem: [Problem reported by user]

Confirm from rule-advisor output:

• taskAnalysis.mainFocus: Primary focus of the problem
• mandatoryChecks.taskEssence: Root problem beyond surface symptoms
• selectedRules: Applicable rule sections
• warningPatterns: Patterns to avoid

0.4 Reflecting in investigator Prompt

Include the following in investigator prompt:

1. Problem essence (taskEssence)
2. Key applicable rules summary (from selectedRules)
3. Investigation focus (investigationFocus): Convert warningPatterns to "points prone to confusion or oversight in this investigation"
4. For change failures, additionally include:
   • Detailed analysis of the change content
   • Commonalities between cause change and affected area
   • Determination of whether the change is a "correct fix" or "new bug" with comparison baseline selection

Diagnosis Flow Overview

Problem → investigator → verifier → solver ─┐
                 ↑                          │
                 └── coverage insufficient ─┘
                      (max 2 iterations)

coverage sufficient → Report

Context Separation: Pass only structured JSON output to each step. Each step starts fresh with the JSON data only.

Execution Steps

Register the following using TaskCreate and execute:

Step 1: Investigation (investigator)

Agent tool invocation:

subagent_type: investigator
description: "Investigate problem"
prompt: |
  Comprehensively collect information related to the following phenomenon.

  Phenomenon: [Problem reported by user]

  Problem essence: [taskEssence from Step 0.3]
  Investigation focus: [investigationFocus from Step 0.4]

  [For change failures, additionally include:]
  Change details: [What was changed]
  Affected area: [What broke]
  Shared components: [Commonalities between cause and effect]

Expected output: pathMap (execution paths per symptom), failurePoints (faults found at each node), impactAnalysis per failure point, unexplored areas, investigation limitations

Step 2: Investigation Quality Check

Review investigation output:

Quality Check (verify JSON output contains the following):

• pathMap exists with at least one symptom, and each symptom has at least one path with nodes listed
• Each failure point has: location, upstreamDependency, symptomExplained, causalChain (reaching a stop condition), checkStatus, evidence with a source citing a specific file or location
• Each failure point has comparisonAnalysis (normalImplementation found or explicitly null)
• causeCategory for each failure point is one of: typo / logic_error / missing_constraint / design_gap / external_factor
• investigationSources covers at least 3 distinct source types (code, history, dependency, config, document, external)
• Investigation covers investigationFocus items (when provided in Step 0.4)
• All nodes on mapped paths have been checked (no path was abandoned after finding the first fault)

If quality insufficient: Re-run investigator specifying missing items explicitly:

prompt: |
  Re-investigate with focus on the following gaps:
  - Missing: [list specific missing items from quality check]

  Previous investigation results (for context, do not re-investigate covered areas):
  [Previous investigation JSON]

design_gap Escalation:

When investigator output contains causeCategory: design_gap or recurrenceRisk: high:

1. Insert user confirmation before verifier execution
2. Use AskUserQuestion: "A design-level issue was detected. How should we proceed?"
   • A: Attempt fix within current design
   • B: Include design reconsideration
3. If user selects B, pass includeRedesign: true to solver

Proceed to verifier once quality is satisfied.

Step 3: Verification (verifier)

Agent tool invocation:

subagent_type: verifier
description: "Verify investigation results"
prompt: Verify the following investigation results.

Investigation results: [Investigation JSON output]

Expected output: Coverage check (missing paths, unchecked nodes), Devil's Advocate evaluation per failure point, failure point evaluation with checkStatus, coverage assessment

Coverage Criteria:

• sufficient: Main paths traced, all critical nodes checked, each failure point individually evaluated
• partial: Main paths traced, some nodes unchecked or some failure points at blocked/not_reached
• insufficient: Significant paths untraced, or critical nodes not investigated

Step 4: Solution Derivation (solver)

Agent tool invocation:

subagent_type: solver
description: "Derive solutions"
prompt: Derive solutions based on the following verified failure points.

Confirmed failure points: [verifier's conclusion.confirmedFailurePoints]
Refuted failure points: [verifier's conclusion.refutedFailurePoints]
Failure point relationships: [verifier's conclusion.failurePointRelationships]
Impact analysis: [investigator's impactAnalysis]
Coverage assessment: [sufficient/partial/insufficient]

Expected output: Multiple solutions (at least 3), tradeoff analysis, recommendation and implementation steps, residual risks

Completion condition: coverageAssessment=sufficient

When not reached:

1. Return to Step 1 with unchecked areas identified by verifier as investigation targets
2. Maximum 2 additional investigation iterations
3. After 2 iterations without reaching sufficient, present user with options:
   • Continue additional investigation
   • Execute solution at current coverage level

Step 5: Final Report Creation

Prerequisite: coverageAssessment=sufficient achieved

After diagnosis completion, report to user in the following format:

## Diagnosis Result Summary

### Identified Failure Points
[Confirmed failure points from verification results]
- Per failure point: location, symptom explained, finalStatus

### Verification Process
- Path coverage: [Paths traced and nodes checked]
- Additional investigation iterations: [0/1/2]
- Coverage assessment: [sufficient/partial/insufficient]

### Recommended Solution
[Solution derivation recommendation]

Rationale: [Selection rationale]

### Implementation Steps
1. [Step 1]
2. [Step 2]
...

### Alternatives
[Alternative description]

### Residual Risks
[solver's residualRisks]

### Post-Resolution Verification Items
- [Verification item 1]
- [Verification item 2]

Completion Criteria

• Executed investigator and obtained pathMap, failurePoints, and impactAnalysis
• Performed investigation quality check and re-ran if insufficient
• Executed verifier and obtained coverage assessment
• Executed solver
• Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations)
• Presented final report to user

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Context: UI adjustment on already-implemented features. The verification loop (edit → check against the design source → refine) runs in the parent session.

Execution Pattern

Core Identity: "I am a guided executor. I run the adjustment and the verification loop myself; subagents handle one-shot tasks."

Execution Protocol:

1. Delegate to subagents (one-shot calls): ui-analyzer, work-planner, quality-fixer-frontend.
2. Run in the parent session (multi-step loops and user dialogs): external-resource hearing via AskUserQuestion, write-set confirmation, scale judgment, adjustment edits, verification against the design source, iteration until acceptance.
3. Stop at every [Stop: ...] marker before proceeding.

Initial Mandatory Tasks

Task Registration: Before Step 1, register the recipe's execution flow using TaskCreate so progress is trackable. Register Steps 1-7 below as individual tasks plus a final task "Verify completion against Completion Criteria". Update status using TaskUpdate as each step starts and completes.

Workflow Overview

Adjustment request → external resource hearing (parent session, AskUserQuestion)
                                  ↓
                     ui-analyzer (subagent: fetch external sources + analyze code + propose candidateWriteSet)
                                  ↓
                     write-set confirmation (parent session, AskUserQuestion)
                                  ↓
                     scale judgment on confirmed write set (documentation-criteria matrix)
                                  ↓
            ┌────────────────────┴────────────────────┐
            ↓                                          ↓
   (1-2 files: inline)                  (3-5 files: work-planner subagent → [Stop])
            ↓                                          ↓
            └─→ adjustment + verification (parent session) ←──┘
                                  ↓
                     quality-fixer-frontend (subagent: typecheck/lint/test)
                                  ↓
                     commit

Scope Boundaries

Included in this skill:

• External resource hearing per the external-resource-context skill
• UI fact gathering via ui-analyzer
• Scale judgment via documentation-criteria's Creation Decision Matrix
• Optional work plan creation via work-planner
• Adjustment edits and verification against the design source (run in this session)
• Quality verification via quality-fixer-frontend
• Commit per adjustment unit

Responsibility Boundary: This skill completes when the adjustment is committed and quality has passed. Adjustment work is end-to-end within this recipe; parent session owns edits, verification loops, quality-result routing, and commits.

Escalation Boundary: Escalate to the full frontend design phase when the request requires PRD, UI Spec, Design Doc, new architecture, multi-screen redesign, or any ADR Creation Condition from documentation-criteria.

Adjustment request: $ARGUMENTS

Execution Flow

Step 1: External Resource Hearing

Run the hearing protocol per the external-resource-context skill (frontend domain).

Step 2: UI Fact Gathering

• Invoke ui-analyzer using Agent tool
  • subagent_type: "dev-workflows-frontend:ui-analyzer"
  • description: "UI fact gathering for adjustment"
  • prompt: "requirement_analysis: { affectedFiles: [files inferred from the adjustment request], scale: 'small', purpose: 'UI adjustment', technicalConsiderations: [] }. requirements: [adjustment request]. target_components: [components named in the request]. ui_spec_path: [path if an existing UI Spec covers the affected components, else absent]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods, and analyze the existing UI codebase. Populate candidateWriteSet[] with the files most likely to require modification."

Step 3: Scale Judgment

Execute Skill: documentation-criteria (loads the Creation Decision Matrix and ADR Creation Conditions used in this step and in the Escalation Boundary).

1. Read candidateWriteSet[] from ui-analyzer output.
2. Present the candidate list to the user via AskUserQuestion: "Confirmed write set for this adjustment? (a) accept high-confidence entries / (b) accept all entries / (c) edit list manually". On c, send a follow-up plain message asking the user to paste the edited file list, then proceed with that list.
3. Apply the Creation Decision Matrix from the documentation-criteria skill to the confirmed write set count:
   • 0 files: The adjustment request did not map to any existing file. Escalate to the user with the message "No write target identified from the adjustment request. Please clarify which component(s) should change, or run the full frontend design phase if this is a new feature." Stop this recipe.
   • 1-2 files: Direct adjustment, no work plan.
   • 3-5 files: Work plan required.
   • 6+ files OR any ADR Creation Condition triggered (architecture changes, contract changes affecting 3+ locations, complex multi-state logic, etc.): Adjustment scope exceeded. Escalate the user to the full frontend design phase. Stop this recipe.

Step 4: Plan Creation (Conditional)

Branch on the scale outcome.

Branch A — 1-2 files

No work plan. Build a minimal adjustment context for the parent session:

• Adjustment request (verbatim)
• ui-analyzer focusAreas[] (raw fact_id; the ui: prefix is only applied when merging with codebase-analysis facts in a Fact Disposition Table, which Branch A does not do)
• Affected files list
• External resources fetched_summary and access methods that the verification loop will use

Present the adjustment context to the user for review.

• [STOP]: User confirms the adjustment context covers the work.

Branch B — 3-5 files

Create a right-sized work plan. Invoke work-planner using Agent tool:

• subagent_type: "dev-workflows-frontend:work-planner"
• description: "Adjustment work plan"
• prompt: "Create a work plan for this UI adjustment. Adjustment request: [verbatim]. ui_analysis: [ui-analyzer JSON]. External resources: docs/project-context/external-resources.md. Scale: 3-5 files (no Design Doc, no ADR). Each phase should be implementable as 1-3 commits. Include a quality checklist matched to the affected components: visual verification, accessibility, i18n parity, generated artifact regeneration when relevant. Output path: docs/plans/[YYYYMMDD]-adjust-[short-description].md."

After work-planner returns:

• Present the work plan to the user.
• [STOP]: Wait for plan approval or revision request. If the user requests changes, re-invoke work-planner with revised guidance.

Step 5: Adjustment + Verification (parent session)

For each adjustment unit (per file in Branch A; per work plan phase in Branch B):

1. Plan the edit based on ui-analyzer focusAreas and the relevant external resource (e.g., design origin's fetched_summary).
2. Apply the edit using Edit / Write / MultiEdit on the affected files.
3. Verify against external sources using whichever access method docs/project-context/external-resources.md declares for each axis:
   • Design origin: compare current rendering against the design source via the declared access method (e.g., design-tool MCP, WebFetch from a public URL, file read from a specification path)
   • Visual rendering: capture screenshot or run a smoke check via the declared visual verification method (e.g., browser MCP, E2E test runner CLI invoked via Bash, dev-server URL inspection, Storybook URL)
   • Design system tokens / variants: confirm against the declared design system source (e.g., design-system MCP, package import, Storybook URL, internal documentation path)
4. Refine and re-verify until the adjustment matches the design source, or matches the user-confirmed adjustment target when no separate design source exists.
5. When the adjustment unit converges, proceed to Step 6 for that unit.

When the project-tier file declares no automated verification mechanism for an axis, ask the user to confirm the result manually, or use file-based comparison when a specification file is available.

Step 6: Quality Verification (per adjustment unit)

• Invoke quality-fixer-frontend using Agent tool
  • subagent_type: "dev-workflows-frontend:quality-fixer-frontend"
  • description: "Quality verification for adjustment unit"
  • Build the prompt by branch. Scope is always filesModified; task_file (when passed) is a supplementary hint that quality-fixer-frontend may use to read the document's "Quality Assurance Mechanisms" section.
    • Branch A (1-2 files): omit task_file. Pass filesModified: [list of files edited in this adjustment unit].
    • Branch B (3-5 files): pass task_file: <work plan path> (supplementary hint) AND filesModified: [list of files edited in this adjustment unit] (primary scope).
  • Example (Branch A): prompt: "filesModified: [src/components/Card/Card.tsx, src/components/Card/Card.module.css]. Run quality checks across the listed files."
  • Example (Branch B): prompt: "task_file: docs/plans/[plan-name].md. filesModified: [src/components/Card/Card.tsx, src/components/Card/Card.module.css]. Run quality checks across the listed files."
• Route the quality-fixer-frontend response by status:
  • approved → proceed to Step 7
  • stub_detected → return to Step 5 to complete the implementation for this unit, then re-invoke quality-fixer-frontend
  • blocked → read reason. When "Cannot determine due to unclear specification", surface blockingIssues[] to the user and stop. When "Execution prerequisites not met", surface missingPrerequisites[] with resolutionSteps to the user and stop

Step 7: Commit (per adjustment unit)

Commit the adjustment unit on quality approval. Include the affected files and any regenerated artifacts (CSS module typings, message catalog typings, etc.) flagged by ui-analyzer's generatedArtifacts section.

Then loop back to Step 5 for the next unit (Branch B work plan phase, or next file in Branch A) until all units are committed.

Completion Criteria

• External resource hearing executed (project-tier file written or update explicitly skipped)
• ui-analyzer returned a JSON output, including externalResources fetch_status per axis and candidateWriteSet
• Write set confirmed by the user before scale judgment
• Scale judgment applied to the confirmed write set; 6+ files or ADR conditions escalated to the design phase
• Branch A: adjustment context presented and confirmed; Branch B: work plan approved
• All adjustment units edited and verified using the project's declared verification mechanism (manual confirmation when no automated mechanism is declared)
• Each adjustment unit passed quality-fixer-frontend with explicit filesModified scoping
• Each adjustment unit committed

Output Example

Frontend adjustment completed.
- External resources: docs/project-context/external-resources.md (updated|unchanged)
- UI fact gathering: ui-analyzer focused on [N] components, [M] focus areas, external sources [fetched|partial|not_recorded]
- Scale: <1-2 files | 3-5 files>
- Work plan: <path | not required>
- Adjustment units committed: [count]
- Quality status: all passed

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Orchestrator Definition

Core Identity: "I am an orchestrator." (see subagents-orchestration-guide skill)

Execution Protocol:

1. Delegate all work through Agent tool — invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools")
2. Follow the 4-step task cycle exactly: task-executor-frontend → escalation check → quality-fixer-frontend → commit
3. Enter autonomous mode when user provides execution instruction with existing task files — this IS the batch approval
4. Scope: Complete when all tasks are committed or escalation occurs

CRITICAL: Run quality-fixer-frontend before every commit.

Work plan: $ARGUMENTS

Pre-execution Prerequisites

Work Plan Resolution

Before any task processing, locate the work plan. Resolution rule:

1. List task files in docs/plans/tasks/ matching the single-layer pattern {plan-name}-task-*.md. Layer-aware fullstack tasks ({plan-name}-backend-task-*.md / {plan-name}-frontend-task-*.md) are excluded here so a stale fullstack run does not redirect this recipe to the wrong work plan
2. From the matched files, also exclude every file matching any of these patterns — they originate from other workflow phases and are not implementation tasks for this run's plan: *-task-prep-*.md (readiness preflight tasks), _overview-*.md (decomposition overview file), *-phase*-completion.md (per-phase completion files), review-fixes-*.md (post-implementation review fixes), integration-tests-*-task-*.md (integration-test add-on scaffolding)
3. For each remaining file, extract the {plan-name} prefix as the segment that appears before -task-
4. When at least one task file matches, the work plan is docs/plans/{plan-name}.md for the prefix that has the most recent task-file mtime; ties broken by the lexicographically last {plan-name}
5. When no task file matches the restricted pattern, the work plan is the most-recent-mtime non-template .md in docs/plans/

Consumed Task Set

Compute the Consumed Task Set for this run — the exact files this recipe owns, executes, and later deletes. Use the same restricted pattern as Work Plan Resolution:

1. List task files in docs/plans/tasks/ matching the single-layer pattern {plan-name}-task-*.md for the {plan-name} resolved by Work Plan Resolution. Layer-aware fullstack tasks are excluded
2. Exclude every file matching: *-task-prep-*.md, _overview-*.md, *-phase*-completion.md, review-fixes-*.md, integration-tests-*-task-*.md (these originate from other workflow phases)

Every subsequent reference to "task files" in this recipe — Task Generation Decision Flow, Task Execution Cycle iteration, and Final Cleanup — uses this set, not the unrestricted docs/plans/tasks/*.md glob.

Task Generation Decision Flow

Analyze the Consumed Task Set and determine the action required:

Task Decomposition Phase (Conditional)

When the Consumed Task Set is empty:

1. User Confirmation

No task files in the Consumed Task Set.
Work plan: docs/plans/[plan-name].md

Generate tasks from the work plan? (y/n):

2. Task Decomposition (if approved)

Invoke task-decomposer using Agent tool:

• subagent_type: "dev-workflows-frontend:task-decomposer"
• description: "Decompose work plan"
• prompt: "Read work plan at docs/plans/[plan-name].md and decompose into atomic tasks. Output: Individual task files in docs/plans/tasks/. Granularity: 1 task = 1 commit = independently executable"

3. Verify Generation

Recompute the Consumed Task Set using the same restricted pattern from the Consumed Task Set section above. Confirm it is now non-empty. If it is still empty, escalate to the user — task-decomposer either failed silently or produced files that don't match the expected pattern.

Flow: Task generation → Consumed Task Set recompute → Autonomous execution (in this order)

Pre-execution Checklist

• Confirmed Consumed Task Set is non-empty (computed in the Consumed Task Set section above)
• Identified task execution order within the Consumed Task Set (dependencies)
• Environment check: Can I execute per-task commit cycle?
  • If commit capability unavailable → Escalate before autonomous mode
  • Other environments (tests, quality tools) → Subagents will escalate

Task Execution Cycle (4-Step Cycle)

MANDATORY EXECUTION CYCLE: task-executor-frontend → escalation check → quality-fixer-frontend → commit

For EACH task in the Consumed Task Set, YOU MUST:

1. Register tasks using TaskCreate: Register work steps. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON"
2. Agent tool (subagent_type: "dev-workflows-frontend:task-executor-frontend") → Pass task file path in prompt, receive structured response
3. CHECK task-executor-frontend response:
   • status: "escalation_needed" or "blocked" → STOP and escalate to user
   • requiresTestReview is true → Execute integration-test-reviewer
     • needs_revision → Return to step 2 with requiredFixes
     • approved → Proceed to step 4
   • readyForQualityCheck: true → Proceed to step 4
4. INVOKE quality-fixer-frontend: Execute all quality checks and fixes. Always pass the current task file path as task_file
5. CHECK quality-fixer-frontend response:
   • stub_detected → Return to step 2 with incompleteImplementations[] details
   • blocked → STOP and escalate to user
   • approved → Proceed to step 6
6. COMMIT on approval: Execute git commit

CRITICAL: Parse every sub-agent response for status fields. Execute the matching branch in the 4-step cycle. Proceed to next task only after quality-fixer-frontend returns approved.

Scope Boundary for Subagents

Append the following block to every subagent prompt invoked from this recipe:

Scope boundary for subagents:
Operate within the task scope and referenced files in the prompt.
Use loaded skills to execute that scope.
Escalate when the required fix or investigation falls outside that scope.

Verify task files exist per Pre-execution Checklist, then enter autonomous execution mode. When requirement changes are detected during execution, escalate to the user with the change summary before continuing.

Post-Implementation Verification (After All Tasks Complete)

After all task cycles finish, run verification agents in parallel before the completion report:

1. Invoke both in parallel using Agent tool:

   • code-verifier (subagent_type: "dev-workflows-frontend:code-verifier") → doc_type: design-doc, Design Doc path, code_paths: implementation file list (git diff --name-only main...HEAD)
   • security-reviewer (subagent_type: "dev-workflows-frontend:security-reviewer") → Design Doc path, implementation file list

2. Consolidate results — check pass/fail for each:

   • code-verifier: pass when status is consistent or mostly_consistent. fail when needs_review or inconsistent. Collect discrepancies with status drift, conflict, or gap
   • security-reviewer: pass when status is approved or approved_with_notes. fail when needs_revision. blocked → Escalate to user
   • Present unified verification report to user

3. Fix cycle (when any verifier failed):

   • Consolidate all actionable findings into a single task file
   • Execute task-executor-frontend with consolidated fixes → quality-fixer-frontend
   • Re-run only the failed verifiers (by the criteria in step 2)
   • Repeat until all pass or blocked → Escalate to user

4. All passed → Proceed to Final Cleanup

Final Cleanup

Before the completion report, delete the implementation task files this recipe consumed. Their work is committed; docs/plans/ is ephemeral working state and is not retained between recipe runs:

• Delete every file in the Consumed Task Set
• Delete every file matching docs/plans/tasks/{plan-name}-phase*-completion.md (the per-phase completion files generated by task-decomposer for this {plan-name})
• Delete the corresponding docs/plans/tasks/_overview-{plan-name}.md if present
• Preserve the work plan itself (docs/plans/{plan-name}.md) — the user decides whether to delete it after final review

If task files cannot be deleted (filesystem error), report the failure but do not block the completion report.

Completion Report Contract

Final report must include:

• Task decomposition status
• Implemented task count
• Quality check result
• Commit count
• Cleanup result
• Escalation or blocking summary, if any

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Context: Dedicated to the frontend design phase.

Orchestrator Definition

Core Identity: "I am an orchestrator." (see subagents-orchestration-guide skill)

Execution Protocol:

1. Delegate all work to sub-agents — your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files.
2. Run the frontend design flow below in order (this recipe covers medium/large frontend):
   • Execute: scope bootstrap → codebase-analyzer → [Stop: Scope confirmation] → external resource hearing → ui-analyzer → ui-spec-designer → technical-designer-frontend → code-verifier → document-reviewer → design-sync
   • ui-spec-designer, code-verifier, and design-sync apply when the design output is a Design Doc; all are skipped for ADR-only
   • Stop at every [Stop: ...] marker → Wait for user approval before proceeding
3. Scope: Complete when design documents receive approval

subagents-orchestration-guide usage: Reference the guide only for orchestration principles (Delegation Boundary, Decision precedence, permitted tools), the Scale Determination table, and handoff contracts HC-02 onward. This recipe defines its own start order and subagent prompts. The guide's requirement-analyzer-origin flow, First Action Rule, HC-01, and Call Examples do not apply to this recipe.

CRITICAL: Execute document-reviewer, design-sync (for Design Docs), and all stopping points — each serves as a quality gate. Skipping any step risks undetected inconsistencies.

Workflow Overview

Requirements → scope bootstrap → codebase-analyzer → [Stop: Scope confirmation]
                                                            ↓
                                          external resource hearing (frontend domain)
                                                            ↓
                                                       ui-analyzer
                                                            ↓
                                              ui-spec-designer → [Stop: UI Spec approval]
                                                            ↓
                                              technical-designer-frontend
                                                            ↓
                                              code-verifier → document-reviewer
                                                            ↓
                                                 design-sync → [Stop: Design approval]

Scope Boundaries

Included in this skill:

• Scope bootstrap: locating seed files so codebase-analyzer receives a populated input
• Codebase analysis with codebase-analyzer (entry point of the frontend design phase)
• Scope confirmation with the user, grounded in codebase-analyzer findings
• External resource hearing per the external-resource-context skill
• UI fact gathering with ui-analyzer
• UI Specification creation with ui-spec-designer (prototype code inquiry included)
• ADR creation (if architecture changes, new technology, or data flow changes)
• Design Doc creation with technical-designer-frontend
• Design Doc verification with code-verifier (before document review)
• Document review with document-reviewer
• Design Doc consistency verification with design-sync

Responsibility Boundary: This skill completes with frontend design document (UI Spec/ADR/Design Doc) approval. Work planning and beyond are outside scope.

Execution Flow

Requirements: $ARGUMENTS

Step 1: Scope Bootstrap

codebase-analyzer requires a populated requirement_analysis.affectedFiles. Build that seed with a lightweight, orchestrator-local pass — locating files only, with no deep reading and no design decisions:

1. Extract candidate keywords from the user requirements (feature names, domain nouns, identifiers).
2. Search the repository with Bash (rg, or grep when rg is unavailable) for files matching those keywords.
3. Collect the matched file paths as the seed affectedFiles.
4. When the search returns no files: ask the user which files or modules the design targets (AskUserQuestion), and use that answer as affectedFiles before invoking codebase-analyzer. If the user confirms no related code exists, report that codebase-grounded design does not apply and confirm with the user how to proceed.
5. When the search returns more than ~20 files: the keywords are too broad for a focused design scope. Present the most relevant candidates to the user (AskUserQuestion) and confirm the seed affectedFiles before invoking codebase-analyzer.

This step locates seed files only. Reading files in full, tracing dependencies, and analysis remain codebase-analyzer's responsibility.

Step 2: Codebase Analysis

Invoke codebase-analyzer with its existing schema. The orchestrator constructs requirement_analysis from the Step 1 seed.

• Invoke codebase-analyzer using Agent tool
  • subagent_type: "dev-workflows-frontend:codebase-analyzer", description: "Codebase analysis"
  • prompt: include
    • requirements: the user requirements verbatim
    • requirement_analysis: a JSON object with all four fields — affectedFiles (Step 1 seed), purpose (the user requirements), scale (provisional value from the Scale Determination table applied to the seed file count), technicalConsiderations ({ constraints: [], risks: [], dependencies: [] } — the bootstrap performs no analysis, so the object is present with empty lists)
    • Expected action: analyze the seed files for frontend design guidance (data, contracts, dependencies, quality assurance mechanisms)

Step 3: Scope Confirmation

After codebase-analyzer returns, confirm the design scope with the user before any design work. This is a recipe-local confirmation step. Use AskUserQuestion.

Present, sourced from the codebase-analyzer JSON:

• Target files/modules: analysisScope.filesAnalyzed and the modules they belong to
• Affected layers: layers touched, derived from analysisScope.categoriesDetected and focusAreas
• Unknowns/assumptions: limitations plus any assumptions codebase-analyzer recorded
• Questions before design: open points that need a user answer before design proceeds

Ask the user to choose one:

• Proceed to design with this scope — continue to Step 4
• Correct the scope and re-run — return to Step 1 with the corrected scope; when the user names the corrected files or modules, use those directly as the Step 1 seed instead of re-deriving them by search
• Hold additional hearing, then proceed — gather the missing answers, then continue to Step 4
• Produce an ADR — when the confirmed scope involves architecture changes, new technology, or data flow changes, continue through the flow with an ADR as the design document; Step 6 (UI Specification) is skipped for ADR

After the user confirms the scope, count the confirmed target files and set the scale from the subagents-orchestration-guide Scale Determination table. This confirmed scale supersedes the Step 2 provisional value and determines the design document.

[STOP]: Wait for the user's choice before proceeding.

Step 4: External Resource Hearing

Run the hearing protocol per the external-resource-context skill (frontend domain). The orchestrator owns this step because it requires AskUserQuestion. The skill defines file-existence branching, two-phase hearing (structured axes + self-declaration), and persistence to docs/project-context/external-resources.md.

Step 5: UI Fact Gathering

Invoke ui-analyzer to gather UI facts. It reads the project-tier external-resources file, fetches external UI sources via the inherited MCP/URL access methods, then analyzes the UI codebase. Its output complements the codebase-analyzer output from Step 2 (data, contracts, dependencies, quality assurance mechanisms).

• Invoke ui-analyzer using Agent tool
  • subagent_type: "dev-workflows-frontend:ui-analyzer", description: "UI fact gathering"
  • prompt: include
    • requirements: the user requirements
    • requirement_analysis: a JSON object with all four fields — affectedFiles (analysisScope.filesAnalyzed from Step 2 codebase-analyzer), purpose (the user requirements), scale (the Step 3 confirmed scale), technicalConsiderations ({ constraints: [], risks: [], dependencies: [] })
    • Expected action: read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods, and analyze the existing UI codebase

Both outputs (codebase-analyzer JSON from Step 2 and ui-analyzer JSON from Step 5) are reused by ui-spec-designer in Step 6 and by technical-designer-frontend in Step 7.

Step 6: UI Specification Phase

When the design document is a Design Doc (this step is skipped for ADR-only): after Step 5 output is received, ask the user about prototype code:

Ask the user: "Do you have prototype code for this feature? If so, please provide the path to the code. The prototype will be placed in docs/ui-spec/assets/ as reference material for the UI Spec."

• [STOP]: Wait for user response about prototype code availability

Then create the UI Specification:

• Invoke ui-spec-designer using Agent tool
  • subagent_type: "dev-workflows-frontend:ui-spec-designer"
  • description: "UI Spec creation"
  • Build the prompt by including:
    • Source: an existing PRD in docs/prd/ when one exists for this feature; otherwise the user requirements with the Step 2 codebase-analyzer JSON and the Step 3 confirmed scope
    • ui_analysis: ui-analyzer JSON from Step 5 (includes externalResources fetched_summary and componentStructure / propsPatterns / cssLayout / etc.)
    • Prototype path when provided
  • Example (existing PRD): prompt: "Create UI Spec from PRD at [path]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."
  • Example (no PRD): prompt: "Create UI Spec from these requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. Confirmed scope: [Step 3 confirmed scope]. ui_analysis: [JSON from Step 5 ui-analyzer]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/."
• Invoke document-reviewer to verify UI Spec
  • subagent_type: "dev-workflows-frontend:document-reviewer", description: "UI Spec review", prompt: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"
• [STOP]: Present UI Spec for user approval

Step 7: Design Document Creation Phase

technical-designer-frontend presents at least two architecture alternatives (technology selection, data flow design) with trade-offs for each. Pass the Step 2 codebase-analyzer output and the Step 5 ui-analyzer output:

• Invoke technical-designer-frontend using Agent tool
  • For ADR: subagent_type: "dev-workflows-frontend:technical-designer-frontend", description: "ADR creation", prompt: "Create ADR for [technical decision]. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. Confirmed scope: [Step 3 confirmed scope]. Present at least two alternatives with trade-offs."
  • For Design Doc: subagent_type: "dev-workflows-frontend:technical-designer-frontend", description: "Design Doc creation", prompt: "Create Design Doc based on the requirements. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 5]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Apply code: prefix to codebase-analyzer fact_ids and ui: prefix to ui-analyzer fact_ids when filling the Fact Disposition Table. Present at least two architecture alternatives with trade-offs."
• (Design Doc only) Invoke code-verifier to verify Design Doc against existing code. Skip for ADR.
  • subagent_type: "dev-workflows-frontend:code-verifier", description: "Design Doc verification", prompt: "doc_type: design-doc document_path: [Design Doc path] Verify Design Doc against existing code."
• Invoke document-reviewer to verify consistency (pass code-verifier results for Design Doc; omit for ADR)
  • subagent_type: "dev-workflows-frontend:document-reviewer", description: "Document review", prompt: "Review [document path] for consistency and completeness. codebase_analysis: [codebase-analyzer JSON from Step 2]. ui_analysis: [ui-analyzer JSON from Step 5]. code_verification: [code verification output from this step] (Design Doc only)"

Step 8: Design Consistency Verification

• (Design Doc only) Invoke design-sync using Agent tool. Skip for ADR-only.
  • subagent_type: "dev-workflows-frontend:design-sync", description: "Design consistency check", prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."
• [STOP]: Present the design document, plus design-sync results for a Design Doc, and obtain user approval

Completion Criteria

• Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none)
• Executed codebase-analyzer with a populated requirement_analysis
• Confirmed the design scope with the user and set the scale from the confirmed target files
• Executed external resource hearing per the external-resource-context skill (file written or update explicitly skipped by user)
• Executed ui-analyzer; codebase-analyzer (Step 2) and ui-analyzer (Step 5) outputs reused by ui-spec-designer and technical-designer-frontend
• Created UI Specification with ui-spec-designer (when applicable) — its External Resources Used section is filled
• Created appropriate design document (ADR or Design Doc) with technical-designer-frontend — its External Resources Used subsection is filled when present
• Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only)
• Executed document-reviewer and addressed feedback
• Executed design-sync for consistency verification (skip for ADR-only)
• Obtained user approval for design document

Output Example

Frontend design phase completed.

• UI Specification: docs/ui-spec/[feature-name]-ui-spec.md
• Design document: docs/design/[document-name].md or docs/adr/[document-name].md
• Approval status: User approved

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Context: Dedicated to the frontend planning phase.

Orchestrator Definition

Core Identity: "I am an orchestrator." (see subagents-orchestration-guide skill)

Execution Protocol:

1. Delegate all work to sub-agents — your role is to invoke sub-agents, pass data between them, and report results
2. Follow subagents-orchestration-guide skill planning flow:
   • Execute steps defined below
   • Stop and obtain approval for plan content before completion
3. Scope: See Scope Boundaries below

CRITICAL: When the user requests test generation, always execute acceptance-test-generator first — it provides the test skeleton that work-planner depends on.

Scope Boundaries

Included in this skill:

• Design document selection
• Test skeleton generation with acceptance-test-generator
• Work plan creation with work-planner
• Work plan review with document-reviewer
• Plan approval obtainment

Responsibility Boundary: This skill completes with work plan approval.

Follow the planning process below:

Execution Process

Step 1: Design Document Selection

! ls -la docs/design/*.md | head -10

• Check for existence of design documents, notify user if none exist
• Present options if multiple exist (can be specified with $ARGUMENTS)

Step 2: Test Skeleton Generation Confirmation

• Confirm with user whether to generate test skeletons (integration + fixture-e2e + service-integration-e2e) first
• If user wants generation: acceptance-test-generator generates skeletons across all applicable lanes
  • Invoke acceptance-test-generator using Agent tool:
    • subagent_type: "dev-workflows-frontend:acceptance-test-generator"
    • description: "Test skeleton generation"
    • If UI Spec exists: prompt: "Generate test skeletons from Design Doc at [path]. UI Spec at [ui-spec path]."
    • If no UI Spec: prompt: "Generate test skeletons from Design Doc at [path]."
• Pass integration test file path, fixture-e2e and service-integration-e2e file paths (or null per lane), and e2eAbsenceReason (per lane) to work-planner according to subagents-orchestration-guide "acceptance-test-generator → work-planner" section

Step 3: Work Plan Creation

Invoke work-planner using Agent tool:

• subagent_type: "dev-workflows-frontend:work-planner"

• description: "Work plan creation"

• If test skeletons were generated in Step 2, build the prompt by listing every lane's status:

  • Always include: "Integration test file: [path or 'not generated']"
  • For each E2E lane (fixtureE2e, serviceE2e):
    • When generatedFiles.<lane> is not null: "[lane] test file: [path]"
    • When generatedFiles.<lane> is null: "No [lane] skeleton generated (reason: [e2eAbsenceReason.])"
  • Append placement guidance: "Integration tests are created simultaneously with each phase implementation. fixture-e2e tests are created alongside the UI feature phase. service-integration-e2e tests are executed only in the final phase."

• If test skeletons were not generated: prompt: "Create work plan from Design Doc at [path]."

• Follow subagents-orchestration-guide Prompt Construction Rule for additional prompt parameters

Step 4: Work Plan Review

Invoke document-reviewer to review the work plan:

• subagent_type: "dev-workflows-frontend:document-reviewer"
• description: "Work plan review"
• prompt: "doc_type: WorkPlan target: docs/plans/[plan-name].md. Review semantic traceability to the Design Doc, early verification placement, real-boundary verification coverage, Failure Mode Checklist, and Review Scope."
• The work plan is a derivation of the Design Doc, so plan-fidelity findings are resolved without user input. Branch on the reviewer's verdict.decision: on needs_revision, re-invoke work-planner in update mode with the findings and re-review, repeating until approved or approved_with_conditions. On rejected, escalate to the user.

Step 5: Present for Approval

• Present the reviewed work plan to the user for batch approval. If the user requests changes, re-invoke work-planner with revised parameters and re-run Step 4.
• Highlight steps with unclear scope or external dependencies and ask the user to confirm

Response at Completion

Recommended: End with the following standard response after plan content approval

Frontend planning phase completed.
- Work plan: docs/plans/[plan-name].md
- Status: Approved

Please provide separate instructions for implementation.

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Context: Post-implementation quality assurance for React/TypeScript frontend

Orchestrator Definition

Core Identity: "I am an orchestrator." (see subagents-orchestration-guide skill)

First Action: Register Steps 1-11 using TaskCreate before any execution.

Execution Method

• Compliance validation → performed by code-reviewer
• Security validation → performed by security-reviewer
• Code-side fix path: Fix implementation → task-executor-frontend; Quality checks → quality-fixer-frontend; Re-validation → code-reviewer / security-reviewer
• Design-side update path: DD revision → technical-designer-frontend (update mode); DD review → document-reviewer; cross-DD consistency → design-sync (when multiple DDs exist); Re-validation → code-reviewer

The design-side path applies when the discrepancy reflects code that was correct but the Design Doc became stale, rather than code that violated the Design Doc.

Design Doc (uses most recent if omitted): $ARGUMENTS

Execution Flow

Step 1: Prerequisite Check

# Identify Design Doc
ls docs/design/*.md | grep -v template | tail -1

# Check implementation files
git diff --name-only main...HEAD

Step 2: Execute code-reviewer

Invoke code-reviewer using Agent tool:

• subagent_type: "dev-workflows-frontend:code-reviewer"
• description: "Code compliance review"
• prompt: "Design Doc: [path]. Implementation files: [git diff file list]. Review mode: full. Validate Design Doc compliance and return structured JSON report."

Store output as: $STEP_2_OUTPUT

Step 3: Execute security-reviewer

Invoke security-reviewer using Agent tool:

• subagent_type: "dev-workflows-frontend:security-reviewer"
• description: "Security review"
• prompt: "Design Doc: [path]. Implementation files: [git diff file list]. Review security compliance."

Store output as: $STEP_3_OUTPUT

Step 4: Verdict and Response

If security-reviewer returned blocked: Stop immediately. Report the blocked finding and escalate to user. Do not proceed to fix steps.

Code compliance criteria (considering project stage):

• Prototype: Pass at 70%+
• Production: 90%+ recommended

Security criteria:

• approved or approved_with_notes → Pass
• needs_revision → Fail

Report both results independently using subagent output fields only:

Before presenting to the user, the orchestrator computes a recommended route per finding using the rule below (this rule is internal — do not include it in the user-facing prompt):

Then present to the user (label each finding with its recommended route, grouped by route):

Code Compliance: [complianceRate from code-reviewer]
  Verdict: [verdict from code-reviewer]
  Identifier Match Rate: [identifierMatchRate from code-reviewer]
  Acceptance Criteria:
  - [fulfilled] [item] (confidence: [high/medium/low])
  - [partially_fulfilled] [item]: [gap] — [suggestion] [recommended: c | d]
  - [unfulfilled] [item]: [gap] — [suggestion] [recommended: c | d]
  Identifier Mismatches:
  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location] [recommended: c | d]
  Quality Findings:
  - [category] [location]: [description] — [rationale] [recommended: c]

Security Review: [status from security-reviewer]
  Findings by category:
  - [confirmed_risk] [location]: [description] — [rationale] [recommended: c]
  - [defense_gap] [location]: [description] — [rationale] [recommended: c]
  - [hardening] [location]: [description] — [rationale] [recommended: c]
  - [policy] [location]: [description] — [rationale] [recommended: c]
  Notes: [notes from security-reviewer, if present]

Resolve discrepancies — confirm or override the recommended route per finding:
  c) Code-side fix       — code violates Design Doc; modify code to match
  d) Design-side update  — code is correct; Design Doc is stale, revise it
  s) Skip                — accept current state without changes

Use AskUserQuestion. The default offer is "accept all recommended routes" — a single confirmation for the typical case where the orchestrator's recommendations are correct. When the user wants to override, collect per-finding c/d/s decisions instead. If the user selects s for everything: skip Steps 5-10, proceed to Step 11.

Step 5: Execute Skill

Execute Skill: documentation-criteria (for task file template)

Step 5d: Design-Side Update

Run this step only when the user routed at least one finding to d. When all routes are c or s, skip directly to Step 6.

1. Invoke technical-designer-frontend in update mode using Agent tool:

   • subagent_type: "dev-workflows-frontend:technical-designer-frontend"
   • description: "Design Doc update from review findings"
   • prompt: "Update Design Doc at [path] in update mode. The implementation has diverged in the following ways that the team has decided to ratify in the design rather than in the code: [list of d-routed findings with codeLocation and designDocValue from $STEP_2_OUTPUT]. Reflect the current code behavior in the relevant sections and add a history entry."

2. Invoke document-reviewer to verify the updated Design Doc:

   • subagent_type: "dev-workflows-frontend:document-reviewer"
   • description: "Document review of updated Design Doc"
   • prompt: "Review updated Design Doc at [path] for consistency and completeness."

3. When multiple Design Docs exist (ls docs/design/*.md | grep -v template | wc -l > 1), invoke design-sync:

   • subagent_type: "dev-workflows-frontend:design-sync"
   • description: "Cross-DD consistency check"
   • prompt: "source_design: [updated DD path]. Detect conflicts across all Design Docs after the update."
   • When sync_status: conflicts_found: present conflicts to the user; resolution requires re-invoking technical-designer-frontend for affected DDs.

4. After Step 5d completes:

   • If the user selected d for all findings (no c routes) → skip Steps 6-8, proceed to Step 9 for re-validation
   • If the user selected both d and c → re-evaluate the c-routed findings against the updated DD and drop any that are now satisfied by the DD revision; then proceed to Step 6 with the remaining c findings

Step 6: Create Task File

Create task file at docs/plans/tasks/review-fixes-YYYYMMDD.md Include both code compliance issues and security requiredFixes.

Step 7: Execute Fixes

Invoke task-executor-frontend using Agent tool:

• subagent_type: "dev-workflows-frontend:task-executor-frontend"
• description: "Execute review fixes"
• prompt: "Task file: docs/plans/tasks/review-fixes-YYYYMMDD.md. Apply staged fixes (stops at 5 files)."

Step 8: Quality Check

Invoke quality-fixer-frontend using Agent tool:

• subagent_type: "dev-workflows-frontend:quality-fixer-frontend"
• description: "Quality gate check"
• prompt: "Confirm quality gate passage for fixed files."

Step 9: Re-validate code-reviewer

Invoke code-reviewer using Agent tool:

• subagent_type: "dev-workflows-frontend:code-reviewer"
• description: "Re-validate compliance"
• prompt: "Re-validate Design Doc compliance after fixes. Design Doc: [path]. Implementation files: [file list]. Prior compliance issues: $STEP_2_OUTPUT. Verify each prior issue is resolved (whether resolved code-side or design-side)."

Step 10: Re-validate security-reviewer

Invoke security-reviewer using Agent tool (only if security fixes were applied):

• subagent_type: "dev-workflows-frontend:security-reviewer"
• description: "Re-validate security"
• prompt: "Re-validate security after fixes. Prior findings: $STEP_3_OUTPUT. Design Doc: [path]. Implementation files: [file list]."

Step 11: Final Cleanup and Report

Delete the review-fix task file this recipe created (if any). Its work is committed; docs/plans/ is ephemeral working state and is not retained between recipe runs:

• Delete docs/plans/tasks/review-fixes-YYYYMMDD.md if it exists

If the file cannot be deleted (filesystem error), report the failure but do not block the final report.

Then present the final report:

Code Compliance:
  Initial: [X]%
  Final: [Y]% (if fixes executed)

Security Review:
  Initial: [status]
  Final: [status] (if fixes executed)
  Notes: [notes from approved_with_notes, if any]

Remaining issues:
- [items requiring manual intervention]

Cleanup: review-fixes task file removed

Auto-fixable Items (code-side path)

• Simple unimplemented acceptance criteria
• Error handling additions
• Contract definition fixes
• Function splitting (length/complexity improvements)
• Security confirmed_risk and defense_gap fixes (input validation, auth checks, output encoding)

Non-fixable Items

• Fundamental business logic changes
• Architecture-level modifications
• Committed secrets (blocked → human intervention)

Design-Side Update Triggers

Discrepancies suitable for the design-side path (code is correct, DD became stale):

• Identifier renames where the new identifier reflects the team's current naming
• Behavioral changes that match the original requirement intent better than what the DD captured
• Component splits or merges where the new structure is sound and the DD documented the prior structure
• New ACs that the implementation already satisfies but the DD never enumerated

Scope: Design Doc compliance validation, security review, code-side auto-fixes, and design-side update routing.

Scope Boundary for Subagents

Append the following block to every subagent prompt invoked from this recipe:

Scope boundary for subagents:
Operate within the review scope and referenced files in the prompt.
Use loaded skills to execute that scope.
Escalate when the required fix or investigation falls outside that scope.

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Task Execution with Metacognitive Analysis

Task: $ARGUMENTS

Mandatory Execution Process

Step 1: Rule Selection via rule-advisor (REQUIRED)

Invoke rule-advisor using Agent tool:

• subagent_type: "dev-workflows:rule-advisor"
• description: "Rule selection"
• prompt: "Task: $ARGUMENTS. Select appropriate rules and perform metacognitive analysis."

Step 2: Utilize rule-advisor Output

After receiving rule-advisor's JSON response, proceed with:

1. Understand Task Essence (from taskAnalysis.essence)

   • Focus on fundamental purpose, not surface-level work
   • Distinguish between "quick fix" vs "proper solution"

2. Follow Selected Rules (from selectedRules)

   • Review each selected rule section
   • Apply concrete procedures and guidelines

3. Recognize Past Failures (from metaCognitiveGuidance.pastFailures)

   • Apply countermeasures for known failure patterns
   • Use suggested alternative approaches

4. Execute First Action (from metaCognitiveGuidance.firstStep)

   • Start with recommended action
   • Use suggested tools first

Step 3: Create Task List with TaskCreate

Register work steps using TaskCreate. Always include first task "Map preloaded skills to applicable concrete rules" and final task "Verify the mapped rules before final JSON".

Break down the task based on rule-advisor's guidance:

• Reflect taskAnalysis.essence in task descriptions
• Apply metaCognitiveGuidance.firstStep to first task
• Restructure tasks considering warningPatterns
• Set priorities based on dependency order and warningPatterns severity

Step 4: Execute Implementation

Proceed with task execution following:

• Start with metaCognitiveGuidance.firstStep action from rule-advisor
• Update task structure with TaskUpdate to reflect rule-advisor insights
• Selected rules from rule-advisor
• Task structure (managed via TaskCreate/TaskUpdate)
• Quality standards defined in the selectedRules output from rule-advisor
• Monitor warningPatterns flags throughout execution and adjust approach when triggered

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts.

Context: Dedicated to updating existing design documents.

Orchestrator Definition

Core Identity: "I am an orchestrator." (see subagents-orchestration-guide skill)

First Action: Register Steps 1-6 using TaskCreate before any execution.

Execution Protocol:

1. Delegate all work through Agent tool — invoke sub-agents, pass deliverable paths between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools")
2. Execute update flow:
   • Identify target → Clarify changes → Update document → Review → Consistency check
   • Stop at every [Stop: ...] marker → Wait for user approval before proceeding
3. Scope: Complete when updated document receives approval

CRITICAL: Execute document-reviewer and all stopping points — each serves as a quality gate for document accuracy.

Workflow Overview

Target document → [Stop: Confirm changes]
                        ↓
              technical-designer / technical-designer-frontend / prd-creator (update mode)
                        ↓ (Design Doc only)
              code-verifier → document-reviewer → [Stop: Review approval]
                        ↓ (Design Doc only)
              design-sync → [Stop: Final approval]

Scope Boundaries

Included in this skill:

• Existing document identification and selection
• Change content clarification with user
• Document update with appropriate agent (update mode)
• Document review with document-reviewer
• Consistency verification with design-sync (Design Doc only)

Out of scope (redirect to appropriate skills):

• New requirement analysis
• Work planning or implementation

Responsibility Boundary: This skill completes with updated document approval.

Target document: $ARGUMENTS

Execution Flow

Step 1: Target Document Identification

# Check existing documents
ls docs/design/*.md docs/prd/*.md docs/adr/*.md 2>/dev/null | grep -v template

Decision flow:

Step 2: Document Type and Layer Determination

Determine type from document path, then determine the layer to select the correct update agent:

Layer detection (for Design Doc and ADR): Read the document and determine its layer from content signals:

• Frontend (→ technical-designer-frontend): Document title/scope mentions React, components, UI, frontend; or file contains component hierarchy, state management, UI interactions
• Backend (→ technical-designer): All other cases (API, data layer, business logic, infrastructure)

ADR Update Guidance:

• Minor changes (clarification, typo fix, small scope adjustment): Update the existing ADR file
• Major changes (decision reversal, significant scope change): Create a new ADR that supersedes the original

Step 3: Change Content Clarification [Stop]

Use AskUserQuestion to clarify what changes are needed:

• What sections need updating
• Reason for the change (bug fix findings, spec change, review feedback, etc.)
• Expected outcome after the update

Confirm understanding of changes with user before proceeding.

Step 4: Document Update

Invoke the update agent determined in Step 2:

subagent_type: [Update Agent from Step 2]
description: "Update [Type from Step 2]"
prompt: |
  Operation Mode: update
  Existing Document: [path from Step 1]

  ## Changes Required
  [Changes clarified in Step 3]

  Update the document to reflect the specified changes.
  Add change history entry.

Step 5: Document Review [Stop]

For Design Doc updates only: Before document-reviewer, invoke code-verifier:

subagent_type: code-verifier
description: "Verify updated Design Doc"
prompt: |
  doc_type: design-doc
  document_path: [path from Step 1]
  Verify the updated Design Doc against current codebase.

  Verification focus: Pay special attention to literal identifier referential
  integrity in the updated sections (paths, endpoints, type names, config keys).

Store output as: $CODE_VERIFICATION_OUTPUT

Invoke document-reviewer:

subagent_type: document-reviewer
description: "Review updated document"
prompt: |
  Review the following updated document.

  doc_type: [Design Doc / PRD / ADR]
  target: [path from Step 1]
  mode: standard
  code_verification: $CODE_VERIFICATION_OUTPUT (Design Doc only, omit for PRD/ADR)

  Focus on:
  - Consistency of updated sections with rest of document
  - No contradictions introduced by changes
  - Completeness of change history

Store output as: $STEP_5_OUTPUT

On review result:

• Approved → Proceed to Step 6
• Needs revision → Return to Step 4 with the following prompt (max 2 iterations):

  subagent_type: [Update Agent from Step 2]
  description: "Revise [Type from Step 2]"
  prompt: |
    Operation Mode: update
    Existing Document: [path from Step 1]
  
    ## Review Feedback to Address
    $STEP_5_OUTPUT
  
    Address each issue raised in the review feedback.
  

• After 2 rejections → Flag for human review, present accumulated feedback to user and end

Present review result to user for approval.

Step 6: Consistency Verification (Design Doc only) [Stop]

Skip condition: Document type is PRD or ADR → Proceed to completion.

For Design Doc, invoke design-sync:

subagent_type: design-sync
description: "Verify consistency"
prompt: |
  Verify consistency of the updated Design Doc with other design documents.

  Updated document: [path from Step 1]

On consistency result:

• No conflicts → Present result to user for final approval
• Conflicts detected → Present conflicts to user with AskUserQuestion:
  • A: Return to Step 4 to resolve conflicts in this document
  • B: End and address conflicts separately

Error Handling

Completion Criteria

• Identified target document
• Clarified change content with user
• Updated document with appropriate agent (update mode)
• Executed code-verifier before document-reviewer (Design Doc only)
• Executed document-reviewer and addressed feedback
• Executed design-sync for consistency verification (Design Doc only)
• Obtained user approval for updated document

Output Example

Document update completed.

• Updated document: docs/design/[document-name].md
• Approval status: User approved

Subagents Orchestration Guide

Role: The Orchestrator

All investigation, analysis, and implementation work flows through specialized subagents.

First Action Rule

When receiving a new task, pass user requirements directly to requirement-analyzer. Determine the workflow based on its scale assessment result.

Requirement Change Detection During Flow

During flow execution, monitor user responses for scope-expanding signals:

• Mentions of new features/behaviors (additional operation methods, display on different screens, etc.)
• Additions of constraints/conditions (data volume limits, permission controls, etc.)
• Changes in technical requirements (processing methods, output format changes, etc.)

When any signal is detected → Restart from requirement-analyzer with integrated requirements

Available Subagents

Implementation support:

1. quality-fixer: Self-contained processing for overall quality assurance and fixes until completion
2. task-decomposer: Appropriate task decomposition of work plans
3. task-executor: Individual task execution and structured response
4. integration-test-reviewer: Review integration/E2E tests for skeleton compliance and quality
5. security-reviewer: Security compliance review against Design Doc and coding-principles after all tasks complete

Document creation: 6. requirement-analyzer: Requirement analysis and work scale determination 7. codebase-analyzer: Analyze existing codebase to produce focused guidance for technical design (data, contracts, dependencies, quality assurance mechanisms) 8. ui-analyzer: Read the project's external-resources file, fetch external UI sources (design origin, design system, guidelines) via MCP/URL/file, and analyze existing UI code. Frontend/fullstack features; runs in parallel with codebase-analyzer. Uses disallowedTools to inherit MCP access 9. prd-creator: Product Requirements Document creation 10. ui-spec-designer: UI Specification creation from PRD and optional prototype code (frontend/fullstack features) 11. technical-designer: ADR/Design Doc creation 12. work-planner: Work plan creation from Design Doc and test skeletons 13. document-reviewer: Single document quality and rule compliance check 14. code-verifier: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc 15. design-sync: Design Doc consistency verification across multiple documents 16. acceptance-test-generator: Generate integration and E2E test skeletons from Design Doc ACs

Orchestration Principles

Delegation Boundary: What vs How

The orchestrator passes what to accomplish and where to work. Each specialist determines how to execute autonomously.

Pass to specialists (what/where/constraints):

• Target directory, package, or file paths
• Task file path or scope description
• Acceptance criteria and hard constraints from the user or design artifacts

Let specialists determine (how):

• Specific commands to run (specialists discover these from project configuration and repo conventions)
• Execution order and tool flags
• Which files to inspect or modify within the given scope

Decision precedence when outputs conflict:

1. User instructions (explicit requests or constraints)
2. Task files and design artifacts (Design Doc, PRD, work plan)
3. Objective repo state (git status, file system, project configuration)
4. Specialist judgment

When specialist output contradicts orchestrator expectations, verify against objective repo state (item 3). If repo state confirms the specialist, follow the specialist. Override specialist output only when it conflicts with items 1 or 2.

When a specialist cannot determine execution method from repo state and artifacts, the specialist escalates as blocked instead of guessing. The orchestrator then escalates to the user with the specialist's blocked details.

Task Assignment with Responsibility Separation

Assign work based on each subagent's responsibilities:

What to delegate to task-executor:

• Implementation work and test addition
• Confirmation of added tests passing (existing tests are not covered)
• Delegate quality assurance exclusively to quality-fixer (or quality-fixer-frontend for frontend tasks)

What to delegate to quality-fixer:

• Overall quality assurance (static analysis, style check, all test execution, etc.)
• Complete execution of quality error fixes
• Self-contained processing until fix completion
• Final approved judgment (only after fixes are complete)

Constraints Between Subagents

Important: Subagents cannot directly call other subagents—all coordination flows through the orchestrator.

Explicit Stop Points

Autonomous execution MUST stop and wait for user input at these points. Use AskUserQuestion to present confirmations and questions.

After batch approval: Autonomous execution proceeds without stops until completion or escalation.

Scale Determination and Document Requirements

※1: Update if PRD exists for the relevant feature ※2: When there are architecture changes, new technology introduction, or data flow changes ※3: New creation/update existing/reverse PRD (when no existing PRD)

How to Call Subagents

Execution Method

Each subagent invocation is a fresh Agent tool call, isolating each phase's context; a SendMessage resume reuses the prior agent's context and breaks that isolation. Each call uses:

• subagent_type: Agent name (e.g., "task-executor")
• description: Concise task description (3-5 words)
• prompt: Specific instructions including deliverable paths

Orchestrator's Permitted Tools

The orchestrator coordinates work using only the following tools:

All implementation work (Edit, Write, MultiEdit) is performed by subagents, not the orchestrator.

Prompt Construction Rule

Every subagent prompt must include:

1. Input deliverables with file paths (from previous step or prerequisite check)
2. Expected action (what the agent should do)

Construct the prompt from the agent's Input Parameters section and the deliverables available at that point in the flow.

Two additional rules:

• Subagents see only the Agent prompt and files they read. Include required paths, prior JSON, parameters, and scope constraints explicitly.
• Replace every [placeholder] in examples below with concrete values before invoking the Agent tool.

Call Example (requirement-analyzer)

• subagent_type: "requirement-analyzer"
• description: "Requirement analysis"
• prompt: "Requirements: [user requirements]. Context: [any relevant context]. Perform requirement analysis and scale determination."

Call Example (codebase-analyzer)

• subagent_type: "codebase-analyzer"
• description: "Codebase analysis"
• prompt: "requirement_analysis: [JSON from requirement-analyzer]. prd_path: [path if exists]. requirements: [original user requirements]. Analyze the existing codebase and produce design guidance."

Call Example (ui-analyzer)

• subagent_type: "ui-analyzer"
• description: "UI fact gathering"
• prompt: "requirement_analysis: [JSON from requirement-analyzer]. requirements: [original user requirements]. ui_spec_path: [path if exists]. target_components: [list if focused]. Read docs/project-context/external-resources.md, fetch external UI sources via the declared access methods (MCP / URL / file), and analyze the existing UI codebase. Output the consolidated UI fact JSON."

When invoked alongside codebase-analyzer for frontend or fullstack-frontend work, run both agents in parallel and pass both JSON outputs to consumers (ui-spec-designer for the design phase; technical-designer-frontend for the Design Doc phase).

Call Example (task-executor)

• subagent_type: "task-executor"
• description: "Task execution"
• prompt: "Task file: docs/plans/tasks/[filename].md Please complete the implementation"

Structured Response Specification

Subagents respond in JSON format. Key fields for orchestrator decisions:

• requirement-analyzer: scale, confidence, affectedLayers, adrRequired, scopeDependencies, questions
• codebase-analyzer: analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations
• ui-analyzer: analysisScope.uiConventions, externalResources (designOrigin/designSystem/guidelines/visualVerification with fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], displayConditions[], i18n, accessibility[], generatedArtifacts[], focusAreas[] (raw fact_id; consumers apply ui: prefix when merging with codebase analysis facts), candidateWriteSet[] (with confidence labels), limitations
• code-verifier: status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (including dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass code_paths scoped to changed files)
• task-executor: status (escalation_needed/completed), escalation_type (design_compliance_violation/similar_function_found/investigation_target_not_found/out_of_scope_file/dependency_version_uncertain/binding_decision_violation/test_environment_not_ready), testsAdded, requiresTestReview
• quality-fixer: Input: task_file (path to current task file — always pass this in orchestrated flows). Status: approved/stub_detected/blocked. stub_detected → route back to task-executor with incompleteImplementations[] details for completion, then re-run quality-fixer. blocked → discriminate by reason field: "Cannot determine due to unclear specification" → read blockingIssues[] for specification details; "Execution prerequisites not met" → read missingPrerequisites[] with resolutionSteps — present these to the user as actionable next steps
• document-reviewer: verdict.decision (approved/approved_with_conditions/needs_revision/rejected)
• design-sync: sync_status (synced/conflicts_found)
• integration-test-reviewer: status (approved/needs_revision/blocked), requiredFixes
• security-reviewer: status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes
• acceptance-test-generator: status, generatedFiles.{integration,fixtureE2e,serviceE2e} (path|null per lane), budgetUsage per lane, e2eAbsenceReason per E2E lane (null when emitted; reason enum is owned by acceptance-test-generator and integration-e2e-testing skill)

Handling Requirement Changes

Handling Requirement Changes in requirement-analyzer

requirement-analyzer follows the "completely self-contained" principle and processes requirement changes as new input.

How to Integrate Requirements

Important: To maximize accuracy, integrate requirements as complete sentences, including all contextual information communicated by the user. Result format: raw concatenation of all requirements, followed by a labeled summary (Initial requirement: … / Additional requirement: …).

Update Mode for Document Generation Agents

Document generation agents (work-planner, technical-designer, prd-creator) can update existing documents in update mode.

• Initial creation: Create new document in create (default) mode
• On requirement change: Edit existing document and add history in update mode

Criteria for timing when to call each agent:

• work-planner: Request updates only before execution
• technical-designer: Request updates according to design changes → Execute document-reviewer for consistency check
• prd-creator: Request updates according to requirement changes → Execute document-reviewer for consistency check
• document-reviewer: Always execute before user approval after PRD/ADR/Design Doc creation/update, and after Work Plan creation/update at Medium/Large scale (Small uses a simplified plan with no semantic review — no Design Doc to trace against)

Basic Flow: Planning and Implementation

Always start with requirement-analyzer, then select the minimum planning flow required by scale and affected layers.

Planning flow (per scale)

External resource hearing runs in the orchestrator (it requires AskUserQuestion). ui-analyzer joins codebase-analyzer in parallel only when the work has a frontend surface; for backend-only work the planning flow uses codebase-analyzer alone.

After the planning flow completes and the user grants batch approval, implementation proceeds. Verifying the plan is implementable end-to-end (verification lanes, fixtures, E2E environment) is an optional preflight the user runs at their discretion via the recipe-prepare-implementation recipe; this guide does not invoke any orchestrator above the agent layer.

Then execute the task execution cycle: task-executor → quality-fixer → commit for each task. See "Autonomous Execution Mode" below for full per-task details. At Small scale this cycle still applies — implementation runs through task-executor, not orchestrator-direct edits.

Each agent name in the chain is invoked via the Agent tool (per "Orchestrator's Permitted Tools" above).

Rules:

• Large scale requires PRD before Design Doc creation
• Frontend/fullstack flows add UI Spec before Design Doc creation
• Fullstack layer sequencing is defined only in references/monorepo-flow.md
• design-sync is required whenever multiple Design Docs exist
• task-decomposer begins only after work plan review (document-reviewer, doc_type WorkPlan; Medium/Large) and batch approval
• Work plan review self-heals: on verdict.decision needs_revision, route back to work-planner (update) and re-review until approved/approved_with_conditions; rejected escalates to the user. The work plan is a derivation of the Design Doc, so plan-fidelity findings need no user adjudication

Autonomous Execution Mode

Pre-Execution Environment Check

Principle: Verify subagents can complete their responsibilities

Required environments:

• Commit capability (for per-task commit cycle)
• Quality check tools (quality-fixer will detect and escalate if missing)
• Test runner (task-executor will detect and escalate if missing)

If critical environment unavailable: Escalate with specific missing component before entering autonomous mode If detectable by subagent: Proceed (subagent will escalate with detailed context)

Authority Delegation

After environment check passes:

• Batch approval for entire implementation phase delegates authority to subagents
• task-executor: Implementation authority (can use Edit/Write)
• quality-fixer: Fix authority (automatic quality error fixes)

Definition of Autonomous Execution Mode

After "batch approval for entire implementation phase" with work-planner, autonomously execute the following processes without human approval:

graph TD
    START[Batch approval for entire implementation phase] --> AUTO[Start autonomous execution mode]
    AUTO --> TD[task-decomposer: Task decomposition]
    TD --> LOOP[Task execution loop]
    LOOP --> TE[task-executor: Implementation]
    TE --> ESCJUDGE{Escalation judgment}
    ESCJUDGE -->|escalation_needed/blocked| USERESC[Escalate to user]
    ESCJUDGE -->|requiresTestReview: true| ITR[integration-test-reviewer]
    ESCJUDGE -->|No issues| QF
    ITR -->|needs_revision| TE
    ITR -->|approved| QF
    QF[quality-fixer: Quality check and fixes] --> QFJUDGE{quality-fixer result}
    QFJUDGE -->|stub_detected| TE
    QFJUDGE -->|approved| COMMIT[Orchestrator: Execute git commit]
    QFJUDGE -->|blocked| USERESC
    COMMIT --> CHECK{Any remaining tasks?}
    CHECK -->|Yes| LOOP
    CHECK -->|No| VERIFY[Post-implementation verification]
    VERIFY --> CV[code-verifier: DD consistency check]
    VERIFY --> SEC[security-reviewer: Security review]
    CV --> VRESULT{Verification results}
    SEC --> VRESULT
    VRESULT -->|All passed| REPORT[Completion report]
    VRESULT -->|Any failed| VFIX[task-executor: Verification fixes]
    VFIX --> QF2[quality-fixer: Quality check]
    QF2 --> REVERIFY[Re-run failed verifiers only]
    REVERIFY --> VRESULT
    VRESULT -->|blocked| USERESC

    LOOP --> INTERRUPT{User input?}
    INTERRUPT -->|None| TE
    INTERRUPT -->|Yes| REQCHECK{Requirement change check}
    REQCHECK -->|No change| TE
    REQCHECK -->|Change| STOP[Stop autonomous execution]
    STOP --> RA[Re-analyze with requirement-analyzer]

Post-Implementation Verification Pass/Fail Criteria

Re-run rule: After fix cycle, re-run only verifiers that returned fail. Verifiers that passed on the previous run are not re-run.

Conditions for Stopping Autonomous Execution

Stop autonomous execution and escalate to user in the following cases:

1. Escalation from subagent

   • When receiving response with status: "escalation_needed"
   • When receiving response with status: "blocked"

2. When requirement change detected

   • Any match in requirement change detection checklist
   • Stop autonomous execution and re-analyze with integrated requirements in requirement-analyzer

3. When work-planner update restriction is violated

   • Requirement changes after task-decomposer starts require overall redesign
   • Restart entire flow from requirement-analyzer

4. When user explicitly stops

   • Direct stop instruction or interruption

Task Management: 4-Step Cycle

Per-task cycle:

1. Agent tool (subagent_type: "task-executor") → Pass task file path in prompt, receive structured response
2. Check task-executor response:
   • status: escalation_needed or blocked → Escalate to user
   • requiresTestReview is true → Execute integration-test-reviewer
     • needs_revision → Return to step 1 with requiredFixes
     • approved → Proceed to step 3
   • Otherwise → Proceed to step 3
3. quality-fixer → Quality check and fixes. Always pass the current task file path as task_file
   • stub_detected → Return to step 1 with incompleteImplementations[] details
   • blocked → Escalate to user
   • approved → Proceed to step 4
4. git commit → Execute with Bash (on approved)

Progress Tracking

Register overall phases using TaskCreate. Update each phase with TaskUpdate as it completes.

Main Orchestrator Roles

1. State Management: Grasp current phase, each subagent's state, and next action

2. Information Bridging: Data conversion and transmission between subagents

   • Convert each subagent's output to next subagent's input format
   • Always pass deliverables from previous process to next agent
   • Extract necessary information from structured responses
   • Compose commit messages from changeSummary
   • Explicitly integrate initial and additional requirements when requirements change

   Handoff Contracts

   HC-01: requirement-analyzer → codebase-analyzer

   • Pass: requirement_analysis, prd_path (if exists), original user requirements

   HC-02: codebase-analyzer → technical-designer

   • Pass: full codebase-analyzer JSON as additional context
   • Required downstream uses:
     • focusAreas → canonical disposition-target list for the Fact Disposition Table
     • dataModel, dataTransformationPipelines, qualityAssurance → Existing Codebase Analysis / Verification Strategy / Quality Assurance sections

   HC-03: technical-designer → code-verifier

   • Pass: Design Doc path (doc_type: design-doc)
   • Do not pass code_paths; code-verifier discovers scope from the document

   HC-04: code-verifier + codebase-analyzer → document-reviewer

   • Pass: code_verification JSON and the same codebase_analysis JSON previously given to the designer
   • Purpose: reviewer validates both discrepancy integration and Fact Disposition coverage against focusAreas

   HC-05: code-verifier → next-layer technical-designer (fullstack only)

   • Defined only for multi-layer fullstack flow in references/monorepo-flow.md
   • Pass: prior-layer Design Doc path plus prior_layer_verification
   • Use only discrepancies[] as known issues to address or escalate. Do not infer verified claims that are not explicitly present in the verifier output.

   technical-designer → work-planner

   Pass to work-planner: Design Doc path. Work-planner reads the DD template from documentation-criteria skill, scans all DD sections, and extracts technical requirements in these categories:

   • Verification Strategy: Extracted to work plan header (Correctness Proof Method + Early Verification Point)
   • Implementation targets: Components, functions, or data structures to create or modify
   • Connection/switching/registration: Integration points, dependency wiring, switching methods
   • Contract changes and propagation: Interface changes, data contracts, field propagation across boundaries
   • Verification requirements: Verification methods, test boundaries, integration verification points
   • Prerequisite work: Migration steps, security measures, environment setup

   Work-planner produces a Design-to-Plan Traceability table mapping each extracted item to covering task(s). Items without a covering task must be marked as gap with justification. Unjustified gaps are errors. Justified gaps require user confirmation before plan approval.

   HC-06: acceptance-test-generator → work-planner

   Pass to acceptance-test-generator: Design Doc path; UI Spec path (if exists).

   Orchestrator verification: Every non-null generatedFiles.<lane> path exists on disk. For each null lane, e2eAbsenceReason.<lane> is present (intentional absence, not an error).

   Pass to work-planner: integration / fixture-e2e / service-integration-e2e file paths (or null per lane), per-lane absence reasons, plus timing guidance — integration tests are created alongside each phase implementation, fixture-e2e tests are created alongside the UI feature phase, service-integration-e2e tests are executed only in the final phase.

   On error: Escalate to user when status != completed and integration file generation failed unexpectedly. A null E2E lane with a valid absence reason is not an error.

3. ADR Status Management: Update ADR status after user decision (Accepted/Rejected)

Important Constraints

Recap (defined above): quality-fixer approval before commit; inter-agent communication is JSON; document-reviewer + user approval before proceeding; check next step against work planning flow after approval; resolve conflicts via Decision precedence.

References

• references/monorepo-flow.md: Fullstack (monorepo) orchestration flow

Task Analyzer

Provides metacognitive task analysis and skill selection guidance.

Skills Index

See skills-index.yaml for available skills metadata.

Task Analysis Process

1. Understand Task Essence

Identify the fundamental purpose beyond surface-level work:

Action: Map the user request to one row in the Surface Work → Fundamental Purpose table above. If no row matches, state the fundamental purpose explicitly before proceeding.

2. Estimate Task Scale

Scale affects skill priority:

• Scale >= Large → include documentation-criteria and implementation-approach in selectedSkills with priority high
• Scale = Small → limit selectedSkills to task-type essential skills only (max 3)

3. Identify Task Type

4. Tag-Based Skill Matching

Extract relevant tags from task description and match against skills-index.yaml:

Task: "Implement user authentication with tests"
Extracted tags: [implementation, testing, security]
Matched skills:
  - coding-principles (implementation, security)
  - testing-principles (testing)
  - ai-development-guide (implementation)

5. Implicit Relationships

Consider hidden dependencies:

Output Format

Return structured analysis with skill metadata from skills-index.yaml:

taskAnalysis:
  essence: <string>  # Fundamental purpose identified
  type: <implementation|fix|refactoring|design|quality>
  scale: <small|medium|large>
  estimatedFiles: <number>
  tags: [<string>, ...]  # Extracted from task description

selectedSkills:
  - skill: <skill-name>  # From skills-index.yaml
    priority: <high|medium|low>
    reason: <string>  # Why this skill was selected
    # Pass through metadata from skills-index.yaml
    tags: [...]
    typical-use: <string>
    size: <small|medium|large>
    sections: [...]  # All sections from yaml, unfiltered

Note: Section selection (choosing which sections are relevant) is done after reading the actual SKILL.md files.

Skill Selection Priority

1. Essential - Directly related to task type
2. Quality - Testing and quality assurance
3. Process - Workflow and documentation
4. Supplementary - Reference and best practices

Metacognitive Question Design

Generate 3-5 questions according to task nature:

Warning Patterns

Detect and flag these patterns:

Test Implementation Patterns

Reference Selection

Common Principles

AAA Structure

All tests follow Arrange-Act-Assert:

• Arrange: Set up preconditions and inputs
• Act: Execute the behavior under test
• Assert: Verify the expected outcome

Test Independence

• Each test runs independently without depending on other tests
• No shared mutable state between tests
• Deterministic execution — no random or time dependencies without mocking

Naming

• Test names describe expected behavior from user perspective
• One test verifies one behavior

Language-Agnostic Testing Principles

Test-Driven Development (TDD)

The RED-GREEN-REFACTOR Cycle

Always follow this cycle:

1. RED: Write a failing test first

   • Write the test before implementation
   • Ensure the test fails for the right reason
   • Verify test can actually fail

2. GREEN: Write minimal code to pass

   • Implement just enough to make the test pass
   • Focus on making it work

3. REFACTOR: Improve code structure

   • Clean up implementation
   • Eliminate duplication
   • Improve naming and clarity
   • Keep all tests passing

4. VERIFY: Ensure all tests still pass

   • Run full test suite
   • Check for regressions
   • Validate refactoring didn't break anything

Quality Requirements

Coverage

• Treat coverage as a diagnostic signal for finding untested areas, not a target — a target gets gamed into trivial tests (Goodhart's Law)
• Concentrate tests on critical paths, business logic, and behavior whose regression would matter
• Prioritize meaningful assertions over the coverage number; any CI threshold is the project's config, not a quality goal in itself

Test Characteristics

All tests must be:

• Independent: No dependencies between tests (see Test Independence Verification for detailed criteria)
• Reproducible: Same input always produces same output
• Fast: Unit tests < 100ms each, integration tests < 1s each, full suite < 10 minutes
• Self-checking: Clear pass/fail without manual verification
• Timely: Written close to the code they test

Test Types

Unit Tests

Purpose: Test individual components in isolation

Characteristics:

• Test single function, method, or class
• Fast execution (milliseconds)
• No external dependencies
• Mock external services
• Majority of your test suite

Integration Tests

Purpose: Test interactions between components

Characteristics:

• Test multiple components together
• May include database, file system, or APIs
• Slower than unit tests
• Verify contracts between modules
• Smaller portion of test suite

End-to-End (E2E) Tests

Purpose: Test complete workflows from user perspective

Characteristics:

• Test entire application stack
• Simulate real user interactions
• Slowest test type
• Fewest in number
• Highest confidence level

Test Design Principles

AAA Pattern (Arrange-Act-Assert)

Structure every test in three clear phases:

// Arrange: Setup test data and conditions
user = createTestUser()
validator = createValidator()

// Act: Execute the code under test
result = validator.validate(user)

// Assert: Verify expected outcome
assert(result.isValid == true)

Adaptation: Apply this structure using your language's idioms (methods, functions, procedures)

One Assertion Per Concept

• Test one behavior per test case
• Multiple assertions OK if testing single concept
• Split unrelated assertions into separate tests

Example: prefer returns error when email is invalid over validates user.

Descriptive Test Names

Test names should clearly describe:

• What is being tested
• Under what conditions
• What the expected outcome is

Recommended format: "should [expected behavior] when [condition]"

Examples:

test("should return error when email is invalid")
test("should calculate discount when user is premium")
test("should throw exception when file not found")

Adaptation: Follow your project's naming convention (camelCase, snake_case, describe/it blocks)

Test Independence

Setup and Teardown

• Use setup hooks to prepare test environment
• Use teardown hooks to clean up resources
• Keep setup minimal and focused
• Ensure teardown runs even if test fails

Mocking and Test Doubles

When to Use Mocks

• Mock external dependencies: APIs, databases, file systems
• Mock slow operations: Network calls, heavy computations
• Mock unpredictable behavior: Random values, current time
• Mock unavailable services: Third-party services

Mocking Principles

• Mock at boundaries, not internally
• Keep mocks simple and focused
• Verify mock expectations when relevant
• Wrap external libraries/frameworks behind adapters and mock the adapter

Data Layer Testing

Mock Limitations for Data Layer

Mocks validate call patterns but cannot verify data layer correctness. The following pass through undetected with mock-only testing:

• Schema mismatches (table names, column names, data types)
• Query correctness (joins, filters, aggregations, grouping)
• Database constraints (NOT NULL, UNIQUE, foreign keys)
• Migration drift (schema changes that make code out of sync)

When Mocks Are Appropriate for Data Access

• Testing business logic that receives data from the data layer (mock the repository, test the service)
• Testing error handling paths (simulating connection failures, timeouts)
• Unit tests where data access is a dependency, not the subject under test

When Mocks Are Insufficient for Data Access

• Testing repository or data access implementations themselves
• Verifying query correctness (joins, filters, aggregations, grouping)
• Testing data integrity constraints
• Testing migration compatibility

Real Database Testing (Environment-Dependent)

Options for verifying data layer correctness against a real database engine:

• Containerized databases for CI environments
• In-memory databases for fast feedback (note: dialect differences may mask issues)
• Dedicated test databases with seed data

The appropriate approach depends on project environment and CI/CD capabilities.

AI-Generated Code and Schema Awareness

• AI-generated data access code has heightened schema hallucination risk
• Generated queries may use correct syntax but reference nonexistent schema elements
• Mock-based tests pass regardless of schema accuracy
• Mitigation: Design Docs should include explicit schema references so that documented schemas can be cross-checked against data access code during review

Test Quality Practices

Keep Tests Active

• Fix or delete failing tests: Resolve failures immediately
• Remove commented-out tests: Fix them or delete entirely
• Keep tests running: Broken tests lose value quickly
• Maintain test suite: Refactor tests as needed

Test Helpers and Utilities

• Create reusable test data builders
• Extract common setup into helper functions
• Build test utilities for complex scenarios
• Share helpers across test files appropriately

What to Test

Focus on Behavior

Test observable behavior, not implementation:

✓ Good: Test that function returns expected output ✓ Good: Test that correct API endpoint is called ✗ Bad: Test that internal variable was set ✗ Bad: Test order of private method calls

Test Public APIs

• Test through public interfaces
• Avoid testing private methods directly
• Test return values, outputs, exceptions
• Test side effects (database, files, logs)

Test Edge Cases

Always test:

• Boundary conditions: Min/max values, empty collections
• Error cases: Invalid input, null values, missing data
• Edge cases: Special characters, extreme values
• Happy path: Normal, expected usage

Test Quality Criteria

These criteria ensure reliable, maintainable tests.

Literal Expected Values

• Use hardcoded literal values in assertions
• Calculate expected values independently from the implementation
• If the implementation has a bug, the test catches it through independent verification
• If expected value equals mock return value unchanged, the test verifies nothing (no transformation occurred)

Result-Based Verification

• Verify final results and observable outcomes
• Assert on return values, output data, or system state changes
• For mock verification, check that correct arguments were passed

Meaningful Assertions

• Every test must include at least one assertion
• Assertions must validate observable behavior
• A test without assertions always passes and provides no value

Appropriate Mock Scope

• Mock direct external I/O dependencies: databases, HTTP clients, file systems
• Use real implementations for internal utilities and business logic
• Over-mocking reduces test value by verifying wiring instead of behavior

Boundary Value Testing

Test at boundaries of valid input ranges:

• Minimum valid value
• Maximum valid value
• Just below minimum (invalid)
• Just above maximum (invalid)
• Empty input (where applicable)

Test Independence Verification

Each test must:

• Create its own test data
• Not depend on execution order
• Clean up its own state
• Pass when run in isolation

Verification Requirements

Before Commit

• ✓ All tests pass — fix failing tests immediately
• ✓ No tests skipped or commented — delete or fix
• ✓ No debug code left in tests
• ✓ Test coverage meets standards
• ✓ No flaky tests — make deterministic
• ✓ Tests run within performance thresholds

Test Organization

File Structure

• Mirror production structure: Tests follow code organization
• Clear naming conventions: Follow project's test file patterns
  • Examples: UserService.test.*, user_service_test.*, test_user_service.*, UserServiceTests.*
• Logical grouping: Group related tests together
• Separate test types: Unit, integration, e2e in separate directories

Performance Considerations

Test Speed

• Unit tests: < 100ms each
• Integration tests: < 1s each
• Full suite: Should run frequently (< 10 minutes)

Optimization Strategies

• Run tests in parallel when possible
• Use in-memory databases for tests
• Mock expensive operations
• Split slow test suites
• Profile and optimize slow tests

Continuous Integration

CI/CD Requirements

• Run full test suite on every commit
• Block merges if tests fail
• Run tests in isolated environments
• Test on target platforms/versions

Test Reports

• Generate coverage reports
• Track test execution time
• Identify flaky tests
• Monitor test trends

Test Design Guardrails

Every Test Must

• Include at least one meaningful assertion
• Create its own test data and clean up its own state
• Pass when run in any order and in isolation
• Test observable behavior through public interfaces
• Keep test logic simple (no branching, no loops)
• Mock only external I/O boundaries, use real implementations for internal logic

Flaky Test Resolution

• Use deterministic time mocking instead of real clocks
• Use fixed seed values instead of random data
• Ensure proper resource cleanup in teardown
• Resolve race conditions with synchronization primitives

Regression Testing

Prevent Regressions

• Add test for every bug fix
• Maintain comprehensive test suite
• Run full suite regularly
• Keep all tests unless the tested functionality is removed

Legacy Code

• Add characterization tests before refactoring
• Test existing behavior first
• Gradually improve coverage
• Refactor with confidence

Testing Best Practices by Language Paradigm

Type System Utilization

For languages with static type systems:

• Leverage compile-time verification for correctness
• Focus tests on business logic and runtime behavior
• Use language's type system to prevent invalid states

For languages with dynamic typing:

• Add comprehensive runtime validation tests
• Explicitly test data contract validation
• Consider property-based testing for broader coverage

Programming Paradigm Considerations

Functional approach:

• Test pure functions thoroughly (deterministic, no side effects)
• Test side effects at system boundaries
• Leverage property-based testing for invariants

Object-oriented approach:

• Test behavior through public interfaces
• Mock dependencies via abstraction layers
• Test polymorphic behavior carefully

Common principle: Adapt testing strategy to leverage language strengths while ensuring comprehensive coverage

Documentation and Communication

Tests as Documentation

• Tests document expected behavior
• Use clear, descriptive test names
• Include examples of usage
• Show edge cases and error handling

Test Failure Messages

• Provide clear, actionable error messages
• Include actual vs expected values
• Add context about what was being tested
• Make debugging easier

TypeScript Development Rules (Frontend)

Basic Principles

• Aggressive Refactoring - Prevent technical debt and maintain health
• Delete code when no current caller exists - YAGNI principle (Kent Beck)

Comment Writing Rules

Code first: names and types carry meaning; a comment must add what code cannot, and one comment per decision is enough. Frontend specifics:

• Comment intent, not markup: explain why a component memoizes, guards, or re-renders — not what the JSX renders
• Timeless content only: Record decisions and rationale; leave chronological history to version control

Type Safety

Absolute Rule: Replace every any with unknown, generics, or union types. any disables type checking and causes runtime errors.

any Type Alternatives (Priority Order)

1. unknown Type + Type Guards: Use for validating external input (API responses, localStorage, URL parameters)
2. Generics: When type flexibility is needed
3. Union Types・Intersection Types: Combinations of multiple types
4. Type Assertions (Last Resort): Only when type is certain

Type Guard Implementation Pattern

function isUser(value: unknown): value is User {
  return typeof value === 'object' && value !== null && 'id' in value && 'name' in value
}

Modern Type Features

• satisfies Operator: const config = { apiUrl: '/api' } satisfies Config - Preserves inference
• const Assertion: const ROUTES = { HOME: '/' } as const satisfies Routes - Immutable and type-safe
• Branded Types: type UserId = string & { __brand: 'UserId' } - Distinguish meaning
• Template Literal Types: type EventName = \on${Capitalize}`` - Express string patterns with types

Type Safety in Frontend Implementation

• React Props/State: TypeScript manages types, unknown unnecessary
• External API Responses: Always receive as unknown, validate with type guards
• localStorage/sessionStorage: Treat as unknown, validate
• URL Parameters: Treat as unknown, validate
• Form Input (Controlled Components): Type-safe with React synthetic events

Type Safety in Data Flow

• Frontend → Backend: Props/State (Type Guaranteed) → API Request (Serialization)
• Backend → Frontend: API Response (unknown) → Type Guard → State (Type Guaranteed)

Type Complexity Management

• Props Design:
  • Props count: 3-7 props ideal (consider component splitting if exceeds 10)
  • Optional Props: 50% or less (consider default values or Context if excessive)
  • Nesting: Up to 2 levels (flatten deeper structures)
• Type Assertions: Review design if used 3+ times
• External API Types: Relax constraints and define according to reality (convert appropriately internally)