settled-reach/docs/discussions/decisions-restructure-si.md

title, description, type, status, round, created

title	description	type	status	round	created
Decisions Restructure — Si Analysis	Si's project management analysis of DECISIONS.md scaling problems and domain-split proposal with ticket linkage improvements	discussion	archived	0	2026-02-11

DECISIONS.md Restructure Analysis — Project Management Perspective

Author: Si (Project Manager / Scrum Master) Date: 2026-02-11 Status: Analysis for Team Leader review Context: DECISIONS.md has grown to 474 lines (31 confirmed, 11 open questions, 10 rejected alternatives) and projects to 1000+ lines within 6-12 months at current velocity

---

1. Problems With Current Approach at Scale

1.1 Context Window Tax

Every agent reads DECISIONS.md at session start. At 474 lines, that's acceptable. At 1000+ lines, agents burn 15-20% of context budget on decisions they don't need. Example: Tyre reads D-028 (dialogue architecture) but only needs D-010, D-020, D-030. Paula reads D-012 (chunk-based maps) but only needs D-005, D-013, D-016, D-024, D-028.

Briefings already duplicate key decisions per agent, creating a two-tier system where DECISIONS.md is "source of truth" but briefings are "what agents actually read." This pattern breaks down as duplication overhead increases.

1.2 Supersession Creates Noise

D-002 superseded by D-005. D-006 superseded by D-027. At 100+ decisions, 20-30% will be superseded. Agents reading chronologically hit dead decisions before finding current ones. Cross-references compound: D-027 supersedes D-006, which was already context for D-005.

Current format requires agents to read superseded decisions to understand why they were superseded. Linear document structure doesn't support "latest version of this decision thread."

1.3 Discovery Requires Full Read

Agent starting work on dialogue system must read all 474 lines to find D-028. Grep for "dialogue" works if you know what to search for. Semantic search via Qdrant works but requires the document to be indexed and assumes the agent knows to search rather than read.

No decision taxonomy. "Architecture" decisions (D-010, D-020, D-030) mixed with "content" decisions (D-024, D-028, D-029) mixed with "scope" decisions (D-006, D-027). An agent asking "what are the architecture decisions?" must read everything.

1.4 Ticket-to-Decision Linkage is One-Way

Tickets have decision_ref pointing to decisions. Decisions don't list which tickets implement them. Traceability breaks: I can see ticket #138 implements D-010 principle 2, but I can't see all tickets implementing D-010 without querying the database.

When planning a sprint to implement D-028, I must:

1. Read D-028
2. Query tickets WHERE decision_ref='D-028'
3. Manually check for tickets implementing dependencies (D-024, D-025)
4. Cross-reference with agent briefings to see who cares about D-028

This workflow doesn't scale.

1.5 Decision Domains Aren't Explicit

Decisions implicitly cluster into domains:

• Architecture: D-010, D-020, D-030 (Tyre's domain)
• Content: D-023, D-024, D-025, D-028, D-029 (Gestalt/Paula/Mellanie)
• Perception/Camera: D-011, D-015, D-017, D-019 (Tyre/Gestalt)
• Scope/Planning: D-006, D-014, D-027 (Team Leader/Si)
• Process: D-022 (meta)

These domains aren't surfaced in DECISIONS.md. An agent working on perception systems must read all decisions to find the 5 they need.

1.6 Velocity Projection

Current rate: ~10 decisions every 2-3 rounds. Rounds every 2-4 days. Projection:

• 3 months: 60-80 decisions
• 6 months: 100-120 decisions
• 12 months: 150-200 decisions

At 150 decisions × 15 lines average = 2250 lines. Unreadable. Linear format breaks.

---

2. Options Analysis

Option A: Split by Domain (Multiple Files)

Structure:

decisions/
  architecture.md       # D-010, D-020, D-030
  content.md           # D-023, D-024, D-025, D-028, D-029
  perception.md        # D-011, D-015, D-017, D-019
  scope.md             # D-006, D-014, D-027
  process.md           # D-022
  questions.md         # Q-001 through Q-011
  rejected.md          # R-001 through R-010

How it intersects with ticketing:

• Tickets still have decision_ref field (unchanged)
• Domain files map to agent specializations (Tyre reads architecture.md, Paula reads content.md)
• Sprint planning: "This sprint implements perception systems" → read perception.md + query tickets WHERE decision_ref IN (D-011, D-015, D-017, D-019)

Workflow for Si creating tickets:

1. Decision made in workshop → documented in domain file
2. Create initiative ticket with decision_ref
3. Break into epics/stories with same decision_ref
4. Agent reads their domain file at session start (~50-100 lines vs 474+)

Pros:

• Context-efficient: agents read only their domains
• Git-friendly: changes to content.md don't trigger diffs in architecture.md
• Natural fit for agent specialization
• Scales to 200+ decisions without file size explosion

Cons:

• Cross-domain decisions require taxonomy judgment (where does D-013 POI system go? Content or perception?)
• Cross-references span files ("D-028 depends on D-024" requires reading two files)
• No single source for "all current decisions"
• Discovery across domains still requires knowing which file to read

Migration path:

1. Create decisions/ directory
2. Split DECISIONS.md by domain (one-time editorial pass)
3. Update CLAUDE.md to point to decisions/ directory
4. Update agent briefings to reference specific domain files
5. Archive DECISIONS.md as decisions/archive/DECISIONS-monolith-2026-02-11.md

---

Option B: Move to Database (SQLite)

Structure:

CREATE TABLE decisions (
    id TEXT PRIMARY KEY,  -- 'D-031', 'Q-009', 'R-010'
    type TEXT CHECK(type IN ('confirmed', 'question', 'rejected')),
    title TEXT NOT NULL,
    decision TEXT NOT NULL,  -- Full decision content
    rationale TEXT,
    raised_by TEXT,
    date TEXT,
    supersedes TEXT,  -- 'D-006'
    superseded_by TEXT,  -- 'D-027'
    domain TEXT,  -- 'architecture', 'content', 'perception'
    status TEXT DEFAULT 'active' CHECK(status IN ('active', 'superseded', 'resolved'))
);

CREATE TABLE decision_tags (
    decision_id TEXT REFERENCES decisions(id),
    tag TEXT,  -- 'architecture', 'multiplayer', 'v0.1'
    PRIMARY KEY (decision_id, tag)
);

CREATE TABLE decision_refs (
    decision_id TEXT REFERENCES decisions(id),
    references TEXT,  -- 'D-010', 'D-024'
    PRIMARY KEY (decision_id, references)
);

How it intersects with ticketing:

• Decisions and tickets in same database
• Query: "Show me all tickets implementing architecture decisions"

  SELECT t.* FROM tickets t
  JOIN decisions d ON t.decision_ref = d.id
  WHERE d.domain = 'architecture' AND d.status = 'active'
  

• Bidirectional traceability: "Show me all decisions with no implementing tickets"
• Dependency graph: "Show me all decisions D-028 depends on (direct + transitive)"

Workflow for Si creating tickets:

1. Decision made in workshop
2. Insert into decisions table with domain tags
3. Create ticket with decision_ref
4. Query: "What decisions have tickets in backlog?" to prioritize sprints

Pros:

• Queryable: agents can ask "show me active architecture decisions" via connector
• Bidirectional traceability: decision → tickets and tickets → decision
• Supersession handled via status field (filter WHERE status='active')
• No context window tax: agents query for what they need
• Cross-reference graph is queryable (transitive dependencies)
• Integrates with existing ticket workflow (same database)

Cons:

• Not git-friendly: decisions are data, not documents
• Diff tracking requires custom tooling (export snapshots to git?)
• Loses markdown formatting richness (code blocks, lists, tables)
• Requires CLI wrapper for agent access (sqlite-query "SELECT...")
• No semantic search (Qdrant can't index database rows)
• Human readability suffers (agents prefer reading markdown to SQL output)

Migration path:

1. Extend schema.sql with decisions tables
2. Write migration script to parse DECISIONS.md → INSERT statements
3. Update /ticket skill to query both tickets and decisions
4. Export active decisions to decisions/current.md on every change (git tracking)
5. Agents query database for work, read exported markdown for context

---

Option C: Hybrid — Domain Files + Database View Layer

Structure:

decisions/
  architecture.md       # Source of truth (git-tracked)
  content.md
  perception.md
  scope.md
  process.md
  questions.md
  rejected.md

db/
  commonwealth.db       # SQLite with decisions view table

connectors/
  decisions-sync.py     # Parses *.md → syncs to DB

decisions table schema:

-- View layer, synced from markdown files
CREATE TABLE decisions (
    id TEXT PRIMARY KEY,
    domain TEXT,  -- derived from source file
    title TEXT,
    file_path TEXT,  -- 'decisions/architecture.md'
    line_number INTEGER,  -- position in source file
    status TEXT,
    supersedes TEXT,
    superseded_by TEXT,
    indexed_at TEXT
);

How it works:

• Domain markdown files are source of truth (human-editable, git-tracked)
• Sync script parses files and populates decisions table
• Agents read markdown for context (50-100 lines per domain)
• Agents query database for relationships (tickets implementing X, dependencies of Y)
• Qdrant indexes markdown files (semantic search works)

How it intersects with ticketing:

• Best of both: readable source + queryable relationships
• Query: "Show me all tickets implementing content decisions"

  SELECT t.* FROM tickets t
  JOIN decisions d ON t.decision_ref = d.id
  WHERE d.domain = 'content' AND d.status = 'active'
  

• Sprint planning: Read content.md for context, query DB for ticket coverage

Workflow for Si creating tickets:

1. Decision documented in domain markdown file
2. Run decisions-sync to update database
3. Create ticket with decision_ref
4. Query database for sprint planning (decision coverage, dependencies)
5. Agents read markdown for session context (efficient)

Pros:

• Git-friendly: decisions are markdown (diffable, versionable)
• Context-efficient: agents read domain files (~50-100 lines)
• Queryable: database view enables relationship queries
• Semantic search: Qdrant indexes markdown files
• Human-readable source: markdown is the truth
• No loss of formatting: code blocks, tables, links preserved
• Bidirectional traceability via database queries

Cons:

• Requires sync script (new tooling, must run on decision changes)
• Sync can drift if markdown is edited without re-sync
• Additional complexity vs pure markdown or pure database
• Sync script is a new failure point

Migration path:

1. Split DECISIONS.md by domain (Option A structure)
2. Write decisions-sync.py to parse domain files
3. Extend schema.sql with decisions view table
4. Add sync to pre-commit hook or manual workflow
5. Update /ticket skill to query decisions table for context

---

Option D: Keep Monolith, Add Index and Views

Structure:

DECISIONS.md          # Monolith (unchanged)
DECISIONS-INDEX.md    # Auto-generated index by domain
DECISIONS-ACTIVE.md   # Auto-generated view (active decisions only)

Index format:

# Decisions Index

## Architecture
- [D-010: Multiplayer-ready architectural baseline](DECISIONS.md#d-010)
- [D-020: Engine selection — Godot + Rust](DECISIONS.md#d-020)
- [D-030: Testability architecture](DECISIONS.md#d-030)

## Content
- [D-023: Three-tier content model](DECISIONS.md#d-023)
- [D-024: NPC generation model](DECISIONS.md#d-024)
...

How it works:

• DECISIONS.md remains single source of truth
• Script generates index grouped by domain (lightweight taxonomy)
• Script generates DECISIONS-ACTIVE.md (filters superseded decisions)
• Agents read index to find relevant decisions, jump to DECISIONS.md section

Pros:

• Minimal change to current workflow
• Git-friendly (generated files can be committed or .gitignored)
• Index improves discovery without restructuring source

Cons:

• Doesn't solve context window tax (agents still read full DECISIONS.md for detail)
• Index generation requires taxonomy metadata in decisions (manual tagging)
• No query capability (database relationships still missing)
• Scales poorly beyond 200 decisions (index helps but monolith remains)

Migration path:

1. Add domain tags to each decision (one-time editorial pass)
2. Write index-generator script
3. Add to pre-commit hook or manual workflow
4. Agents read index first, DECISIONS.md for detail

---

3. Recommended Approach: Option C (Hybrid)

3.1 Rationale

The hybrid approach intersects optimally with how Si manages tickets and plans sprints:

For sprint planning:

• Read domain file (content.md) to understand decisions in scope
• Query database: "Show me all tickets implementing D-024, D-025, D-028"
• Query database: "What decisions are implemented? What's in backlog?"
• Create sprint plan with decision coverage metrics

For ticket creation:

• Workshop produces decision → document in domain file
• Sync to database
• Create initiative ticket with decision_ref
• Break into epics/stories (same decision_ref)
• Database now shows decision → ticket graph

For dependency tracking:

• Decision cross-references stored in markdown (human-readable)
• Sync script parses references → decision_refs table
• Query: "What decisions must be implemented before D-028?"
• Query: "What tickets are blocked by incomplete D-024 implementation?"

For agent coordination:

• Agents read their domain files at session start (50-100 lines, not 474)
• Briefings reference domain files: "Read decisions/architecture.md for D-010, D-020, D-030"
• Query capability means agents can ask "what decisions changed since last session?"

For Team Leader:

• Git diffs show decision changes in readable markdown
• Database view shows project-level metrics (decisions implemented, coverage %)
• Semantic search via Qdrant works (indexes markdown files)

3.2 Why Not the Alternatives

Why not Option A (domain files only)?

• Loses queryable relationships. Sprint planning requires manual cross-file reading.
• No bidirectional traceability (decision → tickets requires manual search).

Why not Option B (database only)?

• Not git-friendly. Decisions are design artifacts, not just data.
• Loses markdown formatting richness.
• No semantic search (Qdrant can't index SQL rows).
• Agents must query for context vs. reading curated documents.

Why not Option D (monolith + index)?

• Doesn't solve context window tax (index helps discovery but agents still read full file).
• No query capability for ticket relationships.
• Scales poorly beyond 200 decisions.

3.3 What Makes Hybrid Optimal for Si's Workflow

As Project Manager, my core workflows are:

1. Sprint planning: Need to see decision coverage and ticket implementation status
2. Ticket creation: Need to trace decisions → initiatives → epics → stories
3. Dependency tracking: Need to understand decision dependencies and ticket blockers
4. Team coordination: Need to point agents to relevant context efficiently
5. Status reporting: Need to show progress metrics (decisions implemented, backlog burn-down)

Hybrid approach supports all five:

1. Database query shows decision coverage per sprint
2. decision_ref linkage works unchanged, database view adds reverse lookup
3. decision_refs table enables dependency graph queries
4. Domain files give agents efficient context (read content.md, not all 474 lines)
5. Database enables metrics queries (% decisions with tickets, % tickets in backlog)

Pure markdown (Option A) fails on 1, 2, 5. Pure database (Option B) fails on 4. Monolith+index (Option D) fails on 1, 2, 3, 5.

---

4. Detailed Proposal: Hybrid Implementation

4.1 Directory Structure

decisions/
  README.md                    # Overview, explains domain taxonomy
  architecture.md              # D-010, D-020, D-030, etc.
  content.md                   # D-023, D-024, D-025, D-028, D-029
  perception.md                # D-011, D-015, D-017, D-019
  scope-planning.md            # D-006, D-014, D-027
  process-meta.md              # D-022
  questions.md                 # Q-001 through Q-011 (active questions)
  rejected.md                  # R-001 through R-010 (rejected alternatives)
  archive/
    DECISIONS-monolith.md      # Original monolith (historical reference)

db/
  schema.sql                   # Extended with decisions tables
  connectors/
    decisions-sync.py          # Parses decisions/*.md → syncs to DB

4.2 Domain Taxonomy

Architecture — Technical foundation decisions that constrain implementation

• Infrastructure (client-server, ECS, serialization)
• Engine and tooling choices
• Performance budgets
• Testability and determinism
• Examples: D-010, D-020, D-030

Content — How narrative, NPCs, and world content are created

• Content tiers and templates
• NPC generation models
• Dialogue systems
• Population and entanglement
• Examples: D-023, D-024, D-025, D-028, D-029

Perception — How the player observes and interacts with the world

• Camera and viewport
• Fog and line-of-sight
• Perception modes
• Sound propagation
• Examples: D-011, D-015, D-017, D-018, D-019

Scope/Planning — What we're building and when

• Prototype scope
• Vertical slice definition
• Map specifications
• Milestone goals
• Examples: D-006, D-014, D-027

Process/Meta — How the team works

• Workflow decisions
• Documentation practices
• Collaboration protocols
• Examples: D-022

Core/Foundation — High-level project direction (doesn't fit other domains)

• Project concept
• Design pillars
• Multiplayer philosophy
• Examples: D-001, D-003, D-005, D-007, D-008, D-009

4.3 Database Schema Extension

-- decisions table (view layer, synced from markdown)
CREATE TABLE decisions (
    id TEXT PRIMARY KEY,                    -- 'D-031', 'Q-009', 'R-010'
    type TEXT NOT NULL CHECK(type IN ('confirmed', 'question', 'rejected')),
    domain TEXT NOT NULL,                   -- 'architecture', 'content', etc.
    title TEXT NOT NULL,
    status TEXT DEFAULT 'active' CHECK(status IN ('active', 'superseded', 'resolved')),
    supersedes TEXT,                        -- 'D-006'
    superseded_by TEXT,                     -- 'D-027'
    date TEXT,
    raised_by TEXT,
    file_path TEXT NOT NULL,                -- 'decisions/architecture.md'
    line_start INTEGER,                     -- line number in source file
    line_end INTEGER,
    synced_at TEXT DEFAULT (datetime('now'))
);

-- decision cross-references (parsed from "See D-XXX" mentions)
CREATE TABLE decision_refs (
    decision_id TEXT NOT NULL REFERENCES decisions(id),
    references TEXT NOT NULL,               -- 'D-010', 'D-024'
    ref_type TEXT DEFAULT 'depends-on' CHECK(ref_type IN ('depends-on', 'related', 'supersedes')),
    PRIMARY KEY (decision_id, references)
);

-- decision tags (flexible taxonomy)
CREATE TABLE decision_tags (
    decision_id TEXT NOT NULL REFERENCES decisions(id),
    tag TEXT NOT NULL,                      -- 'v0.1', 'multiplayer', 'critical'
    PRIMARY KEY (decision_id, tag)
);

CREATE INDEX idx_decisions_domain ON decisions(domain);
CREATE INDEX idx_decisions_status ON decisions(status);
CREATE INDEX idx_decision_refs_references ON decision_refs(references);

4.4 Sync Script Specification

Input: decisions/*.md files Output: Populated decisions, decision_refs, decision_tags tables Trigger: Manual (make decisions-sync) or pre-commit hook

Parsing logic:

# decisions-sync.py pseudo-code

for file in glob('decisions/*.md'):
    domain = derive_domain_from_filename(file)  # architecture.md → 'architecture'

    for decision_block in parse_markdown_sections(file):
        # Extract from heading: "### D-031: Time system — game clock and day phases"
        id = extract_id(decision_block.heading)  # 'D-031'
        title = extract_title(decision_block.heading)

        # Extract from content
        type = infer_type(id)  # D-xxx → confirmed, Q-xxx → question, R-xxx → rejected
        date = extract_field(decision_block, 'Date:')
        raised_by = extract_field(decision_block, 'Raised by:')
        supersedes = extract_field(decision_block, 'Supersedes:')
        superseded_by = extract_field(decision_block, 'Superseded by:')

        # Infer status
        if superseded_by:
            status = 'superseded'
        elif type == 'question' and has_resolution_link(decision_block):
            status = 'resolved'
        else:
            status = 'active'

        # Store decision
        upsert_decision(id, type, domain, title, status, supersedes, superseded_by,
                       date, raised_by, file, line_start, line_end)

        # Parse cross-references (mentions of D-XXX, Q-XXX in content)
        refs = extract_decision_mentions(decision_block.content)
        for ref in refs:
            upsert_decision_ref(id, ref, infer_ref_type(ref, supersedes))

        # Parse tags (could be explicit metadata or inferred)
        tags = extract_tags(decision_block)  # e.g., from "Tags: v0.1, critical"
        for tag in tags:
            upsert_decision_tag(id, tag)

Validation:

• Warn if decision references non-existent decision
• Warn if superseded decision is still marked active
• Warn if decision has no domain file match

4.5 Workflow Changes

For Qatux (documenting decisions)

1. Workshop produces decision
2. Determine domain (architecture/content/perception/scope/process/core)
3. Add decision to appropriate decisions/domain.md file
4. Run make decisions-sync (or let pre-commit hook do it)
5. Decision now queryable via database

For Si (creating tickets)

1. Read domain file for context (e.g., decisions/content.md)
2. Query: SELECT * FROM tickets WHERE decision_ref='D-028' to see existing coverage
3. Create initiative ticket with decision_ref='D-028'
4. Break into epics/stories with same decision_ref
5. Query: SELECT d.id, d.title, COUNT(t.id) as ticket_count FROM decisions d LEFT JOIN tickets t ON d.id = t.decision_ref WHERE d.domain='content' GROUP BY d.id to see coverage

For agents (reading context)

1. Briefing says "Read decisions/architecture.md for D-010, D-020, D-030"
2. Agent reads 50-100 lines (not 474)
3. If agent needs cross-domain context, briefing lists additional files
4. Agent can query: db/connectors/sqlite-query "SELECT * FROM decisions WHERE id='D-028'" for on-demand lookup

For Team Leader (tracking progress)

1. Query: "How many decisions have implementing tickets?"

   SELECT d.domain,
          COUNT(DISTINCT d.id) as total_decisions,
          COUNT(DISTINCT t.decision_ref) as decisions_with_tickets,
          COUNT(t.id) as total_tickets
   FROM decisions d
   LEFT JOIN tickets t ON d.id = t.decision_ref
   WHERE d.status = 'active' AND d.type = 'confirmed'
   GROUP BY d.domain
   

2. Review git diffs on decisions/*.md to see what changed
3. Semantic search via Qdrant: "What decisions relate to multiplayer?"

---

5. Migration Path

Phase 1: Split Monolith (Week 1)

1. Create decisions/ directory
2. Create domain files with README explaining taxonomy
3. Perform one-time editorial pass to split DECISIONS.md by domain
   • Architecture: D-010, D-020, D-030
   • Content: D-023, D-024, D-025, D-028, D-029
   • Perception: D-011, D-015, D-017, D-018, D-019
   • Scope: D-006, D-014, D-027
   • Process: D-022
   • Core: D-001, D-003, D-005, D-007, D-008, D-009
   • Questions: Q-001 through Q-011
   • Rejected: R-001 through R-010
4. Archive DECISIONS.md to decisions/archive/DECISIONS-monolith-2026-02-11.md
5. Update CLAUDE.md to reference decisions/ directory

Validation: Agents can read domain files and find all decisions that were in monolith

Phase 2: Build Sync Infrastructure (Week 2)

1. Extend db/schema.sql with decisions, decision_refs, decision_tags tables
2. Write db/connectors/decisions-sync.py
3. Run sync script manually to verify parsing
4. Add make decisions-sync target to Makefile

Validation: After sync, query decisions table and verify all decisions are present with correct metadata

Phase 3: Update Agent Workflows (Week 3)

1. Update agent briefings to reference specific domain files
   • Tyre's briefing: "Read decisions/architecture.md for D-010, D-020, D-030"
   • Paula's briefing: "Read decisions/content.md for D-024, D-028, D-029"
2. Update /ticket skill to query decisions table for context
3. Document query patterns for Si in docs/WORKFLOW-SI.md

Validation: Agent sessions load <200 lines of decision context (vs 474 previously)

Phase 4: Add Query Tooling (Week 4)

1. Create db/connectors/decisions-query wrapper (similar to sqlite-query)
2. Add common queries as make targets:
   • make decisions-coverage — show decision → ticket coverage by domain
   • make decisions-active — list active decisions
   • make decisions-pending — show decisions with no implementing tickets
3. Update Si's workflow documentation with query recipes

Validation: Si can run queries to plan sprints without reading all domain files

Phase 5: Integration and Refinement (Week 5+)

1. Add pre-commit hook to run decisions-sync automatically
2. Re-index decisions/*.md files in Qdrant for semantic search
3. Monitor for drift (markdown edited without sync)
4. Iterate on taxonomy if domains prove wrong

Validation: Team uses domain files + database queries as primary workflow

---

6. Success Metrics

How we know the restructure is working:

Context Efficiency

• Before: Agents read 474 lines of DECISIONS.md per session
• After: Agents read 50-100 lines of domain file(s) per session
• Target: 70% reduction in decision-context token usage

Discovery Time

• Before: Agent must read all decisions to find relevant ones (or grep if they know the term)
• After: Agent reads domain file index (10-20 decisions) or queries database
• Target: Agent finds relevant decision in <60 seconds

Sprint Planning Efficiency

• Before: Si manually reads DECISIONS.md, searches tickets, cross-references by hand
• After: Si queries database for decision coverage, dependency graph, ticket status
• Target: Sprint planning queries run in <5 seconds, return actionable data

Decision Coverage Visibility

• Before: Unknown how many decisions have implementing tickets without manual audit
• After: Query shows decision → ticket coverage by domain
• Target: Team Leader can see coverage metrics on demand

Git Workflow Quality

• Before: DECISIONS.md diffs show all decisions even if only one changed
• After: Git diffs show only changed domain file (smaller, more focused diffs)
• Target: PR reviews can see decision changes without noise

Onboarding (Future)

• Before: New agent reads 474-line monolith to understand project decisions
• After: New agent reads core.md (high-level) + their domain file (specialized)
• Target: Onboarding context reduced by 60-70%

---

7. Risks and Mitigations

Risk: Sync Drift

Description: Markdown files edited without running sync script. Database becomes stale. Likelihood: Medium (human error) Impact: High (query results are wrong) Mitigation:

• Pre-commit hook runs sync automatically
• CI checks that sync is current (hash markdown files, compare to synced_at timestamp)
• Document sync requirement in CLAUDE.md and decisions/README.md

Risk: Taxonomy Errors

Description: Decision placed in wrong domain file. Agent reads wrong file, misses context. Likelihood: Low (taxonomy is fairly clear) Impact: Medium (agent confusion, duplicate work) Mitigation:

• decisions/README.md documents taxonomy with examples
• Cross-domain decisions can be documented in multiple files with reference links
• Periodic taxonomy review (every 50 decisions) to adjust if needed

Risk: Sync Script Bugs

Description: Parser fails to extract metadata, creates corrupt database entries. Likelihood: Low (script is testable) Impact: High (query results are wrong) Mitigation:

• Write unit tests for parser (test fixtures: sample decision blocks)
• Sync script runs validation checks (warn on missing references, supersession conflicts)
• Manual review of sync output on first 3 runs

Risk: Query Complexity

Description: Agents struggle with SQL queries, revert to reading markdown only. Likelihood: Medium (SQL is not natural language) Impact: Low (hybrid still works with markdown-only workflow) Mitigation:

• Provide common queries as make targets (make decisions-coverage, make decisions-pending)
• Document query recipes in Si's workflow guide
• Agents can fall back to reading markdown (sync adds query capability, doesn't remove readable source)

Risk: Qdrant Indexing Lag

Description: Qdrant semantic search returns outdated results if domain files aren't re-indexed. Likelihood: Low (indexing is manual trigger) Impact: Medium (semantic search less useful) Mitigation:

• Document re-indexing workflow in decisions/README.md
• Add make decisions-index target to trigger Qdrant re-index
• Re-index after each decision-producing workshop (manual checklist for Qatux)

---

8. Alternative: Incremental Hybrid (Lower Risk)

If full hybrid (Option C) feels too aggressive, an incremental path:

Phase 1: Split by domain (Option A)

• Immediate benefit: agents read smaller files
• No new tooling required
• Validates taxonomy before building sync infrastructure

Phase 2: Add database view layer (complete Option C)

• Once domain files prove stable, build sync script
• Adds queryability without changing source format
• Agents already familiar with domain files

This path reduces risk by deferring sync tooling until domain split is validated. Cost: sprint planning remains manual during Phase 1.

Recommendation: Proceed with full hybrid. Sync script is low-risk (parser is testable, database is queryable, markdown remains source of truth). Incremental path delays queryability benefits that Si needs for sprint planning.

---

9. Recommendation Summary

Adopt Option C: Hybrid (domain files + database view layer)

Rationale:

• Context-efficient: agents read 50-100 lines per domain, not 474+ monolith
• Git-friendly: decisions are markdown, diffable, versionable
• Queryable: database view enables sprint planning queries, dependency graphs, coverage metrics
• Semantic search: Qdrant indexes markdown files (unchanged workflow)
• Scalable: works at 200+ decisions without explosion
• Intersects optimally with Si's ticket management and sprint planning workflows

Migration path: 5-week phased rollout (split → sync → briefings → queries → integration)

Success metrics: 70% context reduction, <60s decision discovery, <5s sprint queries, on-demand coverage metrics

Risks: Sync drift (mitigated by pre-commit hook), taxonomy errors (mitigated by clear documentation), query complexity (mitigated by make targets and recipes)

---

10. Next Actions

Immediate (this week)

1. Team Leader approval on Option C (hybrid approach)
2. Qatux: Create decisions/ directory structure and README
3. Si: Perform editorial pass to split DECISIONS.md by domain taxonomy

Week 2

4. Tyre: Extend db/schema.sql with decisions tables
5. Tyre: Build decisions-sync.py parser with validation
6. Si: Run initial sync and verify database population

Week 3

7. Qatux: Update agent briefings to reference domain files
8. Si: Update /ticket skill to query decisions table
9. Si: Document query patterns in docs/WORKFLOW-SI.md

Week 4

10. Tyre: Add make targets for common queries (coverage, pending, active)
11. Si: Test sprint planning workflow with queries
12. Team Leader: Review git diff workflow on domain files

Week 5+

13. Tyre: Add pre-commit hook for decisions-sync
14. Qatux: Re-index decisions/*.md in Qdrant
15. Team: Monitor for drift and taxonomy adjustments

---

End of analysis.

File locations:

• Analysis: /var/mnt/data/projects/commonwealth/docs/discussions/decisions-restructure-si.md
• Current monolith: /var/mnt/data/projects/commonwealth/DECISIONS.md (474 lines)
• Current schema: /var/mnt/data/projects/commonwealth/db/schema.sql
• Current tickets: 273 total (24 initiatives, 33 epics, 200 stories, 15 tasks, 1 bug)