Technical Debt Resolution Reference

Reference: Standard Operating Procedure for identifying, resolving, and preventing technical debt in SEA-Forge™.

Document Purpose

This document establishes the canonical process for managing technical debt (TODOs, FIXMEs, incomplete implementations) in the SEA-Forge™ codebase.

Last Major Resolution: 2026-01-04 (100% resolution achieved)

Principles

1. Spec-First Resolution

Rule: Technical debt is always resolved by fixing upstream sources, never by patching generated code.

Hierarchy (upstream → downstream):

1
2
3
4
5
6
7
ADR/PRD/SDS/SEA-DSL  (specifications)
    ↓
JSON Schemas  (validation)
    ↓
Generators  (templates)
    ↓
Generated Code  (output - DO NOT EDIT)

2. Zero-TODO Policy

Policy: New TODOs are prohibited in production code.

Enforcement:

1
2
# Pre-commit hook (configured in .githooks/pre-commit)
git diff --cached | grep '^+.*TODO:' && exit 1

Acceptable TODO Locations:

• Generator templates (generators/**/*.template) - intentional scaffolding
• Workflow templates (.agent/workflows/**) - example code
• Documentation examples (docs/** - in code blocks only)

3. Track-Not-TODO

Instead of TODO, create:

1. GitHub Issue with full context
2. Spec annotation with @track reference
3. Implementation roadmap in relevant SDS

Example:

1
2
3
4
5
6
7
8
9
10
11
# ❌ BAD: Vague TODO
# TODO: Add caching

# ✅ GOOD: Tracked work
# @spec SDS-049 §8.3 - LLM response caching
# @track https://github.com/GodSpeedAI/SEA™/issues/234
# Implementation deferred to Phase 11 per ENGINEERING.SOP.md
async def complete_chat(self, messages):
    # Current: No caching (simple, correct)
    # Future: Redis cache with 5min TTL
    return await self._llm_adapter.complete(messages)

Resolution Workflow

Phase 0: Discover

1
2
3
4
5
6
7
8
9
# Find all TODOs (excluding intentional placeholders)
rg "TODO:|FIXME:" --type py --type ts --type js \
  | grep -v "current_cycle/" \
  | grep -v ".agent/workflows/" \
  | grep -v "generators/" \
  > todos.txt

# Count by file
rg "TODO:|FIXME:" --count-matches

Phase 1: Categorize

For each TODO, determine:

Phase 2: Resolve

For Spec Gaps:

1
2
3
4
5
6
7
8
9
10
11
# 1. Update spec
vim docs/specs/<context>/<context>.sea

# 2. Validate
just sea-validate docs/specs/<context>/<context>.sea

# 3. Regenerate
just pipeline <context>

# 4. Verify determinism
just ci-determinism

For Generator Bugs:

1
2
3
4
5
6
7
8
9
10
11
# 1. Fix generator template
vim generators/<generator>/files/**/*.ts.template

# 2. Rebuild generators
just generator-build

# 3. Regenerate affected contexts
just nx-affected codegen

# 4. Verify determinism
just ci-determinism

For Integration Stubs:

1
2
3
4
5
6
7
8
9
10
11
# 1. Implement actual integration
# See: libs/sea/adapters/acp/src/acp_gateway.py as example

# 2. Add error handling (graceful degradation)
try:
    result = await call_service()
except ServiceUnavailable:
    return fallback_response()

# 3. Write tests
# 4. Document in docs/explanations/

Phase 3: Validate

1
2
3
4
5
6
7
8
# Full validation
just ci

# Specific checks
just ci-lint              # Code quality
just spec-guard           # Spec validation
just ci-determinism       # Regeneration check
just test                 # All tests

Phase 4: Document

Update tracking document:

• docs/playbooks/TODO_RESOLUTION_PLAN.md

Include:

• Category breakdown
• Resolution strategy
• Implementation details
• Acceptance criteria status

Integration Adapter Pattern

Integration adapters (per AGENTS.md §Integration Adapter Exception) can contain handwritten code but must follow this pattern:

Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
"""
<Adapter Name>

Implements: <Port Interface>
Spec: <SDS Reference>
Purpose: Wraps <Third-Party Library> for SEA™ integration
"""

class MyAdapter(MyPort):
    """
    Integration adapter for <Service>.

    Features:
    - <Feature 1>
    - <Feature 2>

    Graceful Degradation:
    1. Primary: <Service call>
    2. Fallback: <Alternative>
    3. Error: <Informative message>
    """

    def __init__(self, ...):
        # Initialize with optional dependencies
        try:
            import optional_lib
            self._lib = optional_lib
        except ImportError:
            self._lib = None

    async def method(self, ...):
        # Multi-tier failover
        if self._lib is None:
            return self._fallback_response()

        try:
            # Primary implementation
            return await self._call_service()
        except ServiceError as e:
            # Fallback
            return self._fallback_response(error=str(e))

    def _fallback_response(self, error=None):
        return {
            "result": None,
            "error": error or "Service unavailable",
            "guidance": "Install: pip install optional_lib"
        }

Requirements

1. Reference SDS in docstring
2. Implement port interface from specs
3. Graceful degradation with multi-tier fallover
4. Informative errors with guidance
5. Unit tests in tests/<context>/
6. Documentation in docs/explanations/

Prevention Strategies

1. Pre-Commit Checks

1
2
3
4
5
6
7
8
9
10
11
# .githooks/pre-commit
#!/bin/bash

# Block new TODOs in production code
if git diff --cached | grep '^+.*TODO:' | grep -v 'generators/\|.agent/\|current_cycle/'; then
  echo "❌ New TODOs prohibited. Create GitHub issue instead."
  exit 1
fi

# Ensure specs validate before commit
just spec-guard || exit 1

2. PR Template

1
2
3
4
5
6
7
## Checklist

- [ ] No new TODOs added (or in allowed locations only)
- [ ] Spec changes include regeneration (`just pipeline <context>`)
- [ ] All tests pass (`just ci`)
- [ ] Determinism verified (`just ci-determinism`)
- [ ] Integration adapters documented in `docs/explanations/`

3. Quarterly Audit

1
2
3
4
5
6
7
8
# Run during sprint planning
./tools/audit_technical_debt.sh

# Outputs:
# - TODO count trend
# - Long-lived TODOs (> 6 months)
# - Orphaned TODOs (no spec reference)
# - Recommendations for cleanup

Case Study: ACP Gateway Resolution (2026-01-04)

Initial State

4 TODOs in libs/sea/adapters/acp/src/acp_gateway.py:

1. Chat message routing
2. Validation service call
3. Pipeline execution
4. Knowledge graph query

Resolution Strategy

Rejected Approach: Leave TODOs with “future implementation” comments.

Accepted Approach: Implement all integrations with graceful degradation.

Implementation

1. Chat Message Routing

1
2
3
4
5
6
7
8
9
# Before: Echo response
response_content = f"[SEA™ Agent] Received: {message.content}"

# After: HTTP call to LLM service with fallback
async with httpx.AsyncClient(timeout=30.0) as client:
    response = await client.post(
        f"{llm_service_url}/v1/chat/completions",
        json={"messages": messages}
    )

2. Knowledge Graph Query

1
2
3
4
5
# Before: Empty results
return {"results": [], "query": sparql}

# After: Dual-mode SPARQL
# Try Oxigraph HTTP → fallback to in-memory rdflib → error message

Results

• ✅ Zero TODOs remaining
• ✅ Production-ready with multi-tier failover
• ✅ All tests pass (13/13)
• ✅ Documentation complete (2 files)

Lessons Learned

1. Implement, don’t defer: Graceful degradation enables production code today
2. Multi-tier failover: Primary + fallback + error = always works
3. Optional dependencies: Use conditional imports for flexibility
4. Document architecture: Explain design decisions in docs/explanations/

Tools & Scripts

Audit Script

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
#!/bin/bash
# tools/audit_technical_debt.sh

echo "=== Technical Debt Audit ==="
echo ""

# Count TODOs by category
echo "Generator Templates:"
rg "TODO:" generators/ --count-matches | wc -l

echo "Production Code:"
rg "TODO:" --type py --type ts \
  | grep -v "generators/\|current_cycle/\|.agent/" \
  | wc -l

echo ""
echo "Long-lived TODOs (> 6 months):"
git log --all --pretty=format: --name-only --diff-filter=A \
  | xargs -I {} git log --format="%ai {}" -- {} \
  | grep "TODO:" \
  | awk '$1 < "'$(date -d '6 months ago' +%Y-%m-%d)'"'

Cleanup Script

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#!/bin/bash
# tools/cleanup_todos.sh <context>

CONTEXT=$1

echo "Converting TODOs to @track annotations in $CONTEXT..."

# Find TODOs in context
rg "TODO:" "libs/$CONTEXT/" -l | while read file; do
  echo "Processing $file..."

  # Extract TODO text
  # Create GitHub issue
  # Replace TODO with @track annotation
  # (implementation left as exercise)
done

Metrics

Track these metrics quarterly:

Related Documentation

• TODO Resolution Plan - Current status
• AGENTS.md - Editing rules and allowed paths
• Integration Adapter Exception
• ACP Gateway Architecture - Resolution case study
• Develop Software - Spec-first workflow
• Debug Workflow - Troubleshooting guide

Summary

Zero technical debt is achievable when:

1. ✅ Specs define all behavior (no “fill in later”)
2. ✅ Generators produce complete implementations
3. ✅ Integrations use graceful degradation
4. ✅ Work is tracked in specs + GitHub issues, not TODOs
5. ✅ Pre-commit hooks enforce policy

SEA-Forge™ Status: 🎉 Zero production TODOs achieved 2026-01-04