Skip to content

docs: reconcile SOUL.md philosophy with actual product scope #904

@arcaven

Description

@arcaven

Problem

Two specific contradictions between SOUL.md's stated philosophy and implemented/planned features:

1. "Three Doors, Not Three Hundred" vs scope expansion

SOUL.md states:

Show 3 tasks. Not 5. Not "all of them with filters." The constraint IS the feature. When in doubt, show less. Resist the urge to add "just one more option."

Also: "If a feature requires more than one story to be useful, reconsider the decomposition."

Reality: The product scope has expanded to 70+ epics and 353+ stories across 7 phases. Features include daily planning mode, seasonal theme variants, dependency graphs, LLM decomposition, statistics dashboards, 8 provider integrations. Most epics have 4-8 stories.

The core three doors constraint is intact in the UX. The tension is about the project's scope, not the UX — but SOUL.md reads as constraining both.

2. "Not a habit tracker (no gamification)" vs Epic 40

SOUL.md's "What ThreeDoors Is NOT":

Not a habit tracker (no streaks, no gamification, no guilt)

Epic 40 (Beautiful Stats Display) includes milestone celebrations, animated counters, and heatmaps. These are gamification patterns. Story 0.63 references a progress view with streak/stats display.

Suggested fix

Either:

  • Update SOUL.md to reflect the evolved philosophy — distinguish the UX constraint (always show 3 doors) from the scope constraint (which has relaxed). Clarify what "no gamification" means when stats visualization is a feature.
  • Rein in features — if SOUL.md is the source of truth, Epic 40's gamification elements should be reconsidered.

This is a human judgment call, not a doc fix.

Context

Surfaced by kos knowledge graph bootstrap (finding-035, _kos/nodes/bedrock/prd-soul-constraint-drift.yaml, _kos/nodes/bedrock/prd-no-gamification-drift.yaml). The graph's cross-layer edges connected SOUL.md (philosophy) to product-scope.md (phases) to the epic list (353 stories) — revealing the gap between stated values and actual scope.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions