gurix/Reklamator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Reklamator/.specify/memory/constitution.md
T
gurixandClaude 0b15d8e3bc Add User model tests, technical debt tracking, and bug fix protocol 
Improvements:
1. Added 15 comprehensive User model unit tests
2. Created TECHNICAL_DEBT.md to track test gaps and known issues
3. Updated constitution with Bug Fix Protocol (v1.1.0)

User Model Tests (tests/unit/test_user_model.py):
- Test user creation and properties
- Test is_active property (Flask-Login integration)
- Test password hashing and verification
- Test serialization (to_dict/from_dict)
- Test CRUD operations (create, load, update, delete)
- Test error conditions (duplicate username, invalid role)

Technical Debt Documentation (docs/TECHNICAL_DEBT.md):
- Missing authentication route tests
- CSRF testing disabled by design
- Dashboard routes not implemented (planned)
- ClamAV integration not fully tested
- All 3 MVP bugs documented with lessons learned

Constitution Amendment (v1.0.0 → v1.1.0):
- Added Bug Fix Protocol requiring:
  - Write failing test before fix
  - Document in TECHNICAL_DEBT.md
  - Commit test and fix together
  - Lessons learned capture

Test Coverage Improvement:
- Before: 10 tests (8 contract + 2 integration)
- After: 26 tests (8 contract + 2 integration + 15 unit + 1 skipped)
- User model: 0% → 100% coverage

Rationale: Bugs found during manual testing revealed insufficient
test coverage. This addresses the gap and establishes process to
prevent future coverage deficiencies.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-16 15:54:24 +02:00

8.2 KiB
Raw Permalink Blame History

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

Bug Fix Protocol

Every bug fix MUST follow this protocol:

  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.

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.1.0 | Ratified: 2025-10-14 | Last Amended: 2025-10-16

Amendment History:

  • 1.1.0 (2025-10-16): Added Bug Fix Protocol requiring tests for all bug fixes and documentation in TECHNICAL_DEBT.md
  • 1.0.0 (2025-10-14): Initial constitution ratified
Reference in New Issue View Git Blame Copy Permalink