is-it-christmas/.specify/memory/constitution.md

is-it-christmas Constitution

Core Principles

I. User Story-Driven Development

Every feature MUST begin with clearly defined, prioritized user stories that are independently testable. Each user story represents a complete slice of functionality that delivers standalone value.

Requirements:

• User stories MUST be prioritized (P1, P2, P3, etc.) with P1 being the most critical
• Each story MUST be independently implementable, testable, and deployable
• User stories MUST include acceptance scenarios in Given/When/Then format
• Implementation MUST enable incremental delivery (MVP = P1 story complete)

Rationale: User story-driven development ensures that every increment delivers real user value, enables parallel development, and allows early validation of the most critical functionality.

II. Specification-First Planning

Features MUST be fully specified before implementation begins. Specifications include user scenarios, functional requirements, success criteria, and technical design documents.

Requirements:

• Every feature MUST have a spec.md with user stories, requirements, and success criteria
• Every feature MUST have a plan.md with technical context, structure, and constitution check
• Complex features MUST include research.md, data-model.md, and contract definitions
• All specifications MUST use technology-agnostic language focusing on "what" not "how"

Rationale: Specification-first planning reduces implementation churn, catches design issues early, enables better collaboration through clear documentation, and provides a reference for validation.

III. Test-Optional with Clear Intent

Testing is OPTIONAL and MUST be explicitly requested. When tests are required, they MUST be written first and MUST fail before implementation.

Requirements:

• Tests are ONLY written when explicitly requested in the feature specification
• When requested, tests MUST follow the Test-Driven Development (TDD) cycle:
  1. Write tests that capture the requirements
  2. Verify tests FAIL (proving they test real behavior)
  3. Implement the feature
  4. Verify tests PASS
• Test types: Contract tests (API/interface contracts), Integration tests (user journeys), Unit tests (component logic)
• Task lists MUST clearly mark test tasks as "OPTIONAL - only if tests requested"

Rationale: Making tests optional reduces overhead for prototypes and simple features while maintaining rigor when quality gates are needed. Explicit test-first approach prevents false confidence from tests written after implementation.

IV. Independent User Story Implementation

Implementation MUST be structured to enable each user story to be developed, tested, and deployed independently without breaking other stories.

Requirements:

• Task lists MUST be organized by user story (Phase 3: User Story 1, Phase 4: User Story 2, etc.)
• Shared infrastructure MUST be completed in a blocking "Foundational" phase before any user story work begins
• Each user story phase MUST include an "Independent Test" description
• Each user story phase MUST end with a checkpoint confirming standalone functionality
• Cross-story dependencies MUST be minimized; when unavoidable, they MUST be explicitly documented

Rationale: Independent user stories enable parallel team work, incremental delivery, easier debugging, and the ability to defer or cut lower-priority stories without impacting core functionality.

V. Simplicity and Justified Complexity

Solutions MUST start simple. Complexity MUST be explicitly justified with documented alternatives that were rejected.

Requirements:

• Default to the simplest solution that meets requirements
• Apply YAGNI (You Aren't Gonna Need It) principles
• When complexity is introduced (additional layers, patterns, frameworks), MUST document:
  • Why the complexity is needed
  • What simpler alternative was considered
  • Why the simpler alternative was insufficient
• Constitution Check violations MUST be tracked in plan.md Complexity Tracking table

Rationale: Unnecessary complexity increases maintenance burden, slows development, and makes onboarding harder. Requiring justification ensures complexity is only introduced when it provides clear value.

Development Workflow

Specification Workflow

1. Clarify (/speckit.clarify): Identify underspecified areas and ask targeted questions
2. Specify (/speckit.specify): Create feature specification with user stories and requirements
3. Plan (/speckit.plan): Generate implementation plan with technical context and design documents
4. Analyze (/speckit.analyze): Cross-check consistency across spec, plan, and tasks
5. Tasks (/speckit.tasks): Generate dependency-ordered task list organized by user story
6. Checklist (/speckit.checklist): Generate custom validation checklists as needed
7. Implement (/speckit.implement): Execute the implementation plan

Implementation Workflow

1. Complete Setup phase (project structure, dependencies, tooling)
2. Complete Foundational phase (blocking infrastructure that all stories need)
3. Implement user stories in priority order (P1 → P2 → P3):
   • If tests requested: Write tests → Verify tests fail → Implement → Verify tests pass
   • If tests not requested: Implement directly
   • Verify story checkpoint (independent functionality)
4. Complete Polish phase (cross-cutting concerns, documentation, validation)

Parallel Execution

• Tasks marked [P] can run in parallel (different files, no dependencies)
• Once Foundational phase completes, different user stories can be implemented in parallel by different team members
• Within a user story, tests (if included) can run in parallel, models can run in parallel

Quality Standards

Documentation Requirements

• Every feature MUST have spec.md with prioritized user stories
• Every feature MUST have plan.md with technical context and structure decisions
• Complex features SHOULD have research.md, data-model.md, and contracts/
• Every feature MUST have tasks.md organized by user story
• All templates MUST clearly indicate placeholders vs. actual content
• Placeholders MUST use [ALL_CAPS] format or NEEDS CLARIFICATION: tags

Code Organization

• Project structure MUST match one of three patterns:
  • Single project: src/ and tests/ at repository root (default)
  • Web application: backend/ and frontend/ directories with separate src/tests
  • Mobile + API: api/ directory plus ios/ or android/ platform directories
• Structure decisions MUST be documented in plan.md
• File paths MUST be explicit in task descriptions (e.g., "Create User model in src/models/user.py")

Validation Gates

• Constitution Check MUST pass before Phase 0 research and be re-checked after Phase 1 design
• Violations MUST be justified in plan.md Complexity Tracking table
• Each user story checkpoint MUST verify independent functionality
• Final validation MUST run quickstart.md if present

Governance

Amendment Procedure

1. Propose amendment with rationale and impact analysis
2. Update constitution.md with new version number:
   • MAJOR: Backward incompatible governance/principle removals or redefinitions
   • MINOR: New principle/section added or materially expanded guidance
   • PATCH: Clarifications, wording, typo fixes, non-semantic refinements
3. Update LAST_AMENDED_DATE to current date (RATIFICATION_DATE stays constant)
4. Prepend Sync Impact Report as HTML comment listing changes
5. Review and update dependent templates and commands
6. Commit with message: docs: amend constitution to vX.Y.Z (summary)

Compliance Review

• All specifications MUST verify compliance with Core Principles
• Constitution Check in plan.md MUST identify and justify any violations
• The /speckit.analyze command SHOULD be used to validate cross-artifact consistency
• This constitution supersedes any conflicting guidance in other documents

Versioning Policy

• Constitution version follows semantic versioning (MAJOR.MINOR.PATCH)
• Version line format: **Version**: X.Y.Z | **Ratified**: YYYY-MM-DD | **Last Amended**: YYYY-MM-DD
• All dates MUST use ISO 8601 format (YYYY-MM-DD)

Version: 1.0.0 | Ratified: 2025-11-11 | Last Amended: 2025-11-11