# Build Testing — Requirements and Emergency Procedures

> **Agent role**: Reference this file for testing requirements and
  emergency procedures when working with build architecture changes.

## Emergency Procedures

### Build System Broken

1. **Immediate**: Revert to last known working commit

2. **Investigation**: Create issue with full error details

3. **Testing**: Verify all platforms work after revert

4. **Documentation**: Update `BUILDING.md` with failure notes

### Platform-Specific Failure

1. **Isolate**: Identify which platform is affected

2. **Test Others**: Verify other platforms still work

3. **Rollback**: Revert platform-specific changes

4. **Investigation**: Debug in isolated environment

## Rollback Playbook

### Immediate Rollback

1. `git revert` or `git reset --hard <prev>`; restore prior `scripts/` or config

   files

2. Rebuild affected targets; verify old behavior returns

3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found

### Rollback Verification

- **Web**: `npm run build:web:dev` and `npm run build:web:prod`

- **Mobile**: `npm run build:android:test` and `npm run build:ios:test`

- **Desktop**: `npm run build:electron:dev` and packaging commands

- **Clean**: Run relevant `clean:*` scripts and verify re-build works

### Android-Specific Rollback Verification

- **Asset Generation**: `npm run build:android --assets` -

  verify resources regenerate

- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes

- **Resource Validation**:

  Check `android/app/src/main/res/` for all required assets

- **Build Modes**: Verify development, test, and production modes all work

- **Resource Fallback**:

  Confirm missing resources trigger automatic regeneration

## Integration Points

### With Version Control

- **Branch Protection**: Require reviews for build script changes

- **Commit Messages**: Must reference ADR for major changes

- **Testing**: All build changes must pass CI/CD pipeline

### With Documentation

- **BUILDING.md**: Must be updated for any script changes

- **README.md**: Must reflect new build requirements

- **CHANGELOG.md**: Must document breaking build changes

### With Testing

- **Pre-commit**: Run basic build validation

- **CI/CD**: Full platform build testing

- **Manual Testing**: Human verification of critical paths

## Competence Hooks

### Why This Works

- **Prevents Build Failures**: Catches issues before they reach production

- **Maintains Consistency**: Ensures all platforms build identically

- **Reduces Debugging Time**: Prevents build system regressions

### Common Pitfalls

- **Silent Failures**: Changes that work on one platform but break others

- **Dependency Conflicts**: Updates that create version incompatibilities

- **Documentation Drift**: Build scripts that don't match documentation

### Next Skill Unlock

- Learn to test build changes across all platforms simultaneously

### Teach-back

- "What three platforms must I test before committing a build script change?"

## Collaboration Hooks

### Team Review Requirements

- **Platform Owners**: iOS, Android, Electron, Web specialists

- **DevOps**: CI/CD pipeline maintainers

- **QA**: Testing infrastructure owners

### Discussion Prompts

- "Which platforms will be affected by this build change?"

- "How can we test this change without breaking existing builds?"

- "What's our rollback plan if this change fails?"

## Self-Check (Before Allowing Changes)

- [ ] **Authorization Level**: Is this change appropriate for the level?

- [ ] **Testing Plan**: Is there a comprehensive testing strategy?

- [ ] **Documentation**: Will BUILDING.md be updated?

- [ ] **Rollback**: Is there a safe rollback mechanism?

- [ ] **Team Review**: Have appropriate stakeholders been consulted?

- [ ] **CI/CD**: Will this pass the build pipeline?

## Continuous Improvement & Feedback

### Feedback Collection

The Build Architecture Guard system includes feedback mechanisms to continuously
  improve its effectiveness:

- **User Feedback**: Script includes feedback prompts for guard improvements

- **Pattern Analysis**:

  Monitor which file patterns trigger false positives/negatives

- **Documentation Gaps**: Track which changes lack proper documentation

- **Testing Effectiveness**: Measure how often guard catches actual issues

### Feedback Integration Process

1. **Collect Feedback**: Monitor guard execution logs and user reports

2. **Analyze Patterns**: Identify common false positives or missed patterns

3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback

4. **Enhance Script**: Update `build-arch-guard.sh` with new validations

5. **Test Changes**: Verify guard improvements don't introduce new issues

6. **Document Updates**: Update guard documentation with new patterns

### Feedback Categories

- **False Positives**: Files flagged as sensitive that shouldn't be

- **False Negatives**: Sensitive files that weren't caught

- **Missing Patterns**: New file types that should be protected

- **Overly Strict**: Patterns that are too restrictive

- **Documentation Gaps**: Missing guidance for specific change types

- **Testing Improvements**: Better validation procedures

### Feedback Reporting

When reporting guard issues, include:

- **File patterns** that triggered false positives/negatives

- **Build system changes** that weren't properly caught

- **Documentation gaps** in current guard rules

- **Testing procedures** that could be improved

- **User experience** issues with guard enforcement

---

**See also**:

- `.cursor/rules/architecture/build_architecture_guard.mdc` for

  core protection guidelines

- `.cursor/rules/architecture/build_validation.mdc` for validation procedures

**Status**: Active testing requirements
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: build_architecture_guard.mdc, build_validation.mdc
**Stakeholders**: Development team, DevOps team, Build team

## Model Implementation Checklist

### Before Build Testing

- [ ] **Test Planning**: Plan comprehensive testing strategy for build changes
- [ ] **Platform Coverage**: Identify all platforms that need testing
- [ ] **Risk Assessment**: Assess testing risks and mitigation strategies
- [ ] **Resource Planning**: Plan testing resources and time requirements

### During Build Testing

- [ ] **Test Execution**: Execute planned tests across all platforms
- [ ] **Issue Tracking**: Track and document any issues found
- [ ] **Feedback Collection**: Collect feedback on testing effectiveness
- [ ] **Documentation**: Document testing procedures and results

### After Build Testing

- [ ] **Result Analysis**: Analyze testing results and identify patterns
- [ ] **Feedback Integration**: Integrate feedback into testing procedures
- [ ] **Process Improvement**: Update testing procedures based on feedback
- [ ] **Team Communication**: Share testing results and improvements with team