git:20260716.aea9523 to git:20260719.3848a77

---

name: ai-development-guide

---

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

## Language-Specific References

For frontend-specific anti-patterns, debugging, and quality checks:

- **React/TypeScript Frontend**: [references/frontend.md](references/frontend.md)

**Value-First Engineering [MANDATORY]**

Explore broadly, then converge on the lowest-lifecycle-cost solution that delivers user value and leaves the system correct and maintainable.

- Resolve verified bugs, failing quality checks, and technical debt within confirmed scope or dependencies required for its outcome; report other findings separately.

- Introduce capabilities, infrastructure, abstractions, or speculative edge-case handling only when a current outcome, verified constraint, or evidence-backed material risk requires them.

- When resolving a known problem falls outside that boundary or materially changes behavior, architecture, or effort, obtain an explicit scope decision.

## Technical Anti-patterns (Red Flag Patterns) [MANDATORY]

**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)

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 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** - EVALUATE unknown elements with minimal verification code first

- **Symptomatic fixes** - Identify root cause with 5 Whys instead of applying surface-level patches

- **Unplanned large-scale changes** - Use incremental approach with phased implementation

**ENFORCEMENT**: Detecting ANY anti-pattern requires IMMEDIATE design review before proceeding

## Fail-Fast Fallback Design Principles

### Core Principle [MANDATORY]

Make errors explicit with full context. Prioritize primary code reliability over fallback implementations. Silent fallbacks are PROHIBITED.

### Implementation Guidelines

#### Default Approach [MANDATORY]

- **Prohibit unconditional fallbacks**: NEVER automatically return default values on errors

- **Make failures explicit**: Errors MUST 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

### 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** [MANDATORY]:

**STEP 1**: Verify Design Doc explicitly defines this fallback

**STEP 2**: Document the business justification

**STEP 3**: Ensure error is logged with full context

**STEP 4**: Add monitoring/alerting for fallback activation

**ENFORCEMENT**: Fallbacks without Design Doc approval are PROHIBITED

## 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

- Similar functionality is technical debt: Repair it when it blocks the current outcome, was caused by the current change, or lies in confirmed scope; otherwise report it separately. When the repair requires an architectural decision, record the decision in an ADR

- When adopting a pattern or dependency from nearby code, verify it is representative across the repository before adopting it

## Quality Assurance Mechanism Awareness

Before executing quality checks, discover applicable quality tools and constraints by inspecting the affected files' types, project manifests, CI pipelines, and configuration:

- Primary detection: inspect affected file types, manifests, configuration, and CI pipelines to identify applicable quality tools

- Check for domain-specific linters or validators such as schema validators, API spec validators, or configuration-file checkers

- Check for domain-specific constraints in project configuration such as naming rules, length limits, or format requirements

- When a task file lists `Quality Assurance Mechanisms`, use that section as supplementary guidance for what to verify

- Include discovered domain-specific checks alongside the standard quality phases below

## Quality Check Workflow [MANDATORY]

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

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 coverage when configured and use it to find gaps

4. **E2E Tests**: Run end-to-end tests

### Phase 4: Final Quality Gate [MANDATORY]

All checks MUST pass before proceeding:

- Zero static analysis errors

- Build succeeds

- All tests pass

- Coverage threshold passes when the project, task file, work plan, or Design Doc defines one. When no threshold is configured, use coverage output only to identify untested critical paths.

**ENFORCEMENT**: Cannot proceed with ANY quality check failures — fix ALL errors before marking task complete

## Implementation Completeness Assurance

### Impact Analysis: Mandatory 3-Stage Process [MANDATORY]

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 to transformations to destination)

- Coupling strength

**3. Identification** - Produce structured report:

```

## Impact Analysis

### Direct Impact

- [Unit]: [Reason and modification needed]

### Indirect Impact

- [System]: [Integration path and 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. [...]

```

**ENFORCEMENT**: CANNOT implement until all 3 stages are documented

### Unused Code Deletion

When unused code is detected:

- Applies to: Code, tests, docs, configs, assets

### Existing Code Modification

```

```

**Principle**: Prefer clean implementation over patching broken code