**Rationale**: Clear specifications prevent scope creep, enable accurate effort estimation, and provide a shared understanding between stakeholders and implementers. Independent testability ensures we can deliver incremental value.
**Rationale**: Test-first development forces clear thinking about requirements and interfaces. It prevents the common trap of writing tests that merely confirm what the code does rather than what it should do. This is non-negotiable because untested code is unmaintainable code.
**Rationale**: Independent stories enable incremental delivery, reduce risk, allow flexible prioritization, and support parallel development when team capacity allows.
### IV. Simplicity & Justification
Complexity MUST be justified. Default to the simplest solution that meets requirements. When introducing:
- Additional abstraction layers
- New dependencies
- Design patterns beyond direct implementation
- Additional projects or services
Document WHY it's needed and what simpler alternative was rejected and why.
**Rationale**: Complexity is expensive. It increases cognitive load, maintenance burden, bug surface area, and onboarding time. Every complexity decision should be a conscious tradeoff with documented reasoning.
### V. Documentation as Code
Documentation MUST live alongside code, be version-controlled, and follow the same review process. Required documentation:
- Feature specifications in `/specs/[###-feature-name]/spec.md`
- Implementation plans in `/specs/[###-feature-name]/plan.md`
- Data models, contracts, and quickstart guides in feature directories
- Constitution (this document) for governance
**Rationale**: Outdated documentation is worse than no documentation. Treating docs as code ensures they stay current, searchable, and reviewable. The Specify framework structure enforces this by design.
## Quality Standards
### Testing Requirements
- **Contract tests**: Required for all public APIs and interfaces
- **Integration tests**: Required for user journeys and cross-component interactions
- **Unit tests**: Optional but encouraged for complex logic
- **Test independence**: Tests MUST NOT depend on execution order
- **Test clarity**: Test names MUST describe what behavior is being verified
### Code Quality
- Clear, self-documenting code preferred over extensive comments
- Comments required only for non-obvious decisions or complex algorithms
- Linting and formatting tools MUST be configured and enforced
- Error handling MUST be explicit and meaningful
- Logging MUST be structured and include sufficient context
## Development Process
### Feature Lifecycle
1.**Specify** (`/speckit.specify`): Create feature specification with user stories
2.**Clarify** (`/speckit.clarify`): Address any ambiguities or underspecified areas
3.**Plan** (`/speckit.plan`): Research, design data models, define contracts
1.**Write a Failing Test**: Create a test that reproduces the bug and currently fails
2.**Verify Failure**: Run the test to confirm it fails with the buggy code
3.**Fix the Bug**: Implement the minimal fix to address the root cause
4.**Verify Success**: Run the test to confirm it now passes
5.**Document**: Add entry to `docs/TECHNICAL_DEBT.md` documenting:
- Bug description and symptoms
- Root cause analysis
- Test coverage added
- Lessons learned
6.**Commit Together**: Test and fix MUST be committed in the same commit or immediately sequential commits
**Rationale**: Bug fixes without tests are incomplete. Tests serve as regression prevention and documentation of expected behavior. If a bug was found manually, it means our test coverage has a gap that must be filled.
**Exceptions**: The only acceptable reason to skip adding a test is if:
- The bug is in test infrastructure itself
- The bug requires external dependencies unavailable in CI (document in TECHNICAL_DEBT.md)
- The bug is in a deprecated component being removed
In all exception cases, document the rationale in the commit message and TECHNICAL_DEBT.md.
- Feature branches named `###-feature-name` where ### is numeric identifier
- Branch created before planning phase begins
- Regular integration to avoid long-lived feature branches
- All changes require review before merging
### Constitution Compliance
Before starting implementation (Phase 0 research), run Constitution Check from `plan.md`. Any violations MUST be documented in the Complexity Tracking table with:
- What rule is being violated
- Why it's necessary for this feature
- What simpler alternative was considered and rejected
All feature specifications, plans, and implementations MUST be reviewed for constitutional compliance. Reviewers MUST verify:
- Specification precedes implementation
- Tests written before code
- User stories are independently testable
- Complexity is justified in Complexity Tracking table when needed
- Required documentation is complete and current
### Conflicts & Precedence
This constitution supersedes all other development guidelines, practices, or conventions. When conflicts arise, this document governs. If this constitution is unclear or incomplete for a specific situation, propose an amendment rather than work around it.
