Technical decision criteria, anti-pattern detection, debugging techniques, and quality check workflow. Use when making technical decisions, detecting code smells, or performing quality assurance.
"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:
Verify Design Doc explicitly defines this fallback
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":
Duplication Count
Action
Reason
1st time
Inline implementation
Cannot predict future changes
2nd time
Consider future consolidation
Pattern beginning to emerge
3rd time
Implement commonalization
Pattern established
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 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
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
Read error message (first line) accurately
Focus on first and last of stack trace
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
Code Style Checking: Verify adherence to style guidelines
Code Formatting: Ensure consistent formatting
Unused Code Detection: Identify dead code and unused imports/variables
Static Type Checking: Verify type correctness (for statically typed languages)
