Reklamator/.specify/memory/constitution.md

Reklamator Constitution

Core Principles

I. Specification-First Development

Every feature MUST begin with a complete specification document before any implementation work begins. Specifications MUST include:

• Prioritized user stories that are independently testable
• Functional requirements with unique identifiers (FR-001, etc.)
• Measurable success criteria
• Edge cases and boundary conditions

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.

II. Test-First Discipline (NON-NEGOTIABLE)

Tests MUST be written before implementation code. The mandatory workflow is:

1. Write tests that capture requirements
2. Verify tests FAIL (proving they test something meaningful)
3. Implement the minimum code to make tests pass
4. Refactor while keeping tests green

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.

III. Independent User Stories

User stories MUST be designed as independently deliverable units of value. Each story:

• Can be implemented without requiring other stories to be complete
• Can be tested in isolation
• Delivers tangible value to users even if it's the only story delivered
• Has an explicitly assigned priority (P1, P2, P3, etc.)

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
4. Tasks (/speckit.tasks): Generate dependency-ordered implementation tasks
5. Implement (/speckit.implement): Execute tasks following test-first discipline
6. Analyze (/speckit.analyze): Verify cross-artifact consistency

Branching & Integration

• 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

Governance

Amendment Process

1. Proposal: Document proposed change with rationale
2. Review: Discuss impact on existing practices and templates
3. Sync: Update all dependent templates and documentation
4. Version: Increment version following semantic versioning
5. Ratify: Record amendment date and version

Versioning Policy

• MAJOR (X.0.0): Backward incompatible changes, principle removals, fundamental redefinitions
• MINOR (x.Y.0): New principles added, sections expanded, new mandatory practices
• PATCH (x.y.Z): Clarifications, wording improvements, typo fixes, non-semantic changes

Compliance Review

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.

Version: 1.0.0 | Ratified: 2025-10-14 | Last Amended: 2025-10-14