sdd-recovery

SDD Recovery

docs/sdd-guidelines.md §6: "Integrity will break. The question is not whether, but when and how to respond."

Detection

Broken integrity manifests as:

Recovery Principle

1. Isolate   — Identify scope of breakage
2. Trace     — Find what can still be verified
3. Reconstruct — Re-establish missing links/reasoning
4. Verify    — Confirm integrity restored

Partial integrity > none. Restore incrementally.

1. Orphan Handling

Design Without @derives

## Caching Layer

{No @derives link}

Options:

Decision flow:

Design item without @derives
    │
    ├─ Can find matching REQ? ──Yes──► Add @derives
    │
    └─ No matching REQ
        │
        ├─ Should feature exist? ──Yes──► Create REQ first
        │
        └─ No ──► Remove design item

REQ Without @aligns-to

## REQ-007: Dark Mode

{No @aligns-to link}

Options:

Test Without @verifies

def test_something():
    # No @verifies
    ...

Options:

Decision Without Context

## DEC-003: Use Redis

{No rationale, no alternatives}

Options:

## DEC-003: Use Redis

`@rationale:` unknown (inherited) — Decision predates SDD adoption.
             Likely chosen for caching performance, but alternatives
             not documented.

2. Contradiction Recovery

Detection

Foundation: "CONSTRAINT-OFFLINE: Must work offline"
     ↓
REQ-005: "Sync data to cloud in real-time"  ← CONFLICT

Resolution Process

1. Identify authority

   Foundation > Requirements > Design
   Earlier decision > Later (unless @supersedes)
   

2. Determine which is wrong

   If...	Then...
   Lower-level wrong	Update lower-level
   Higher-level wrong	Escalate (needs authority)
   Unclear	Document as gap, escalate

3. Resolve

   ## REQ-005: Offline-First Sync
   
   `@aligns-to:` CONSTRAINT-OFFLINE
   
   Queue changes locally; sync when online.
   
   `@rationale:` DEC-007 — Revised from real-time sync to respect 
                 CONSTRAINT-OFFLINE. See DEC-007 for migration plan.
   

4. Propagate — Re-verify dependents

5. Re-run tests — Behavioral tests must still pass

Horizontal Contradiction

REQ-001: "Use localStorage"
REQ-002: "Use IndexedDB"  ← CONFLICT

Resolution:

• Determine which is correct (or if both needed for different purposes)
• Update or remove conflicting REQ
• Document decision if non-obvious

3. Broken Link Recovery

Target Renamed

`@derives:` REQ-005  ← Was renamed to REQ-AUTH-005

Fix: Update reference

`@derives:` REQ-AUTH-005

Target Deleted

`@derives:` REQ-003  ← REQ-003 no longer exists

Options:

Target Never Existed

`@derives:` REQ-999  ← Typo or wrong ID

Fix: Find correct target or acknowledge as orphan

Link Syntax Error

`@derives` REQ-005      ← Missing colon
`@derives:` req-005     ← Wrong case
`@derives:` REQ 005     ← Space instead of hyphen

Fix: Correct syntax

`@derives:` REQ-005

4. Version Mismatch Recovery

# design.md frontmatter
depends_on:
  - requirements.md@1.0.0  ← But requirements.md is now @2.0.0

Process

1. Check changelog — What changed between versions?

2. Assess impact:

   Bump	Action
   MAJOR	Re-verify completely, re-run all tests
   MINOR	Spot-check affected areas
   PATCH	Update version reference only

3. Re-verify affected items

4. Update depends_on to current version

Example

# Before
depends_on:
  - requirements.md@1.0.0

# requirements.md changelog shows:
# v2.0.0: BREAKING - Removed REQ-003, REQ-004

# Action: Find design items @derives REQ-003, REQ-004
#         These are now orphaned → handle as orphans
#         Then update:

depends_on:
  - requirements.md@2.0.0

5. Inheriting Broken Systems

docs/sdd-philosophy.md §7.3: "Pretending integrity exists is worse than admitting it does not."

Principles

Process

1. Assess current state

   inherited_system:
     has_foundation: false
     has_requirements: partial  # Some exist
     has_design: false
     has_tests: true  # But no @verifies
     decisions_documented: false
   

2. Create minimal Foundation

   # {System} Foundation
   
   ## Status
   
   Inherited system. Documentation reconstructed from code analysis.
   
   ## Identity (Inferred)
   
   {What the system appears to do, based on code/behavior}
   
   ## Identity Anchors
   
   - **SCOPE-INFERRED-1:** {observed scope}
   - **CONSTRAINT-INFERRED-1:** {observed constraint}
   
   > ⚠️ Anchors are inferred, not authoritative. Validate with stakeholders.
   

3. Document known unknowns

   ## Unknown Areas
   
   - Authentication flow: Implementation exists, rationale unknown
   - Caching strategy: Redis used, alternatives not evaluated
   - Database schema: No documented design decisions
   

4. Add @verifies to existing tests

   # @verifies: REQ-INFERRED-001
   # Note: REQ inferred from test behavior
   def test_user_login():
       ...
   

5. Build forward — New work follows full SDD

Marking Inherited Items

Use warning markers and track in state file:

## REQ-INFERRED-001: User Authentication

`@aligns-to:` SCOPE-INFERRED-1

Users can log in with email/password.

> ⚠️ **INHERITED:** Requirement reconstructed from code. Original intent unknown.

## DEC-INHERITED-001: PostgreSQL Database

`@rationale:` unknown (inherited) — Database choice predates documentation.
              Assuming standard selection criteria applied.

> ⚠️ **INHERITED:** Decision predates SDD adoption.

Track inherited status in state file (not inline):

# .sdd/state.yaml
items:
  REQ-INFERRED-001:
    status: draft
    inherited: true
    note: "Inferred from existing implementation"

6. Test Failure Recovery

For test setup issues (missing @verifies, wrong directory), see sdd-verify testing.md §10. This section covers test execution failures.

Behavioral Test Fails

test_user_can_create_task FAILED
# @verifies: REQ-001

This means: REQ-001 is not satisfied.

Structural Test Fails

test_token_bucket_refill FAILED
# Tests Design §Rate Limiting

This means: Design implementation broken, but REQ may still be met.

Check: If structural test fails but behavioral test passes → design detail wrong but feature works. Still fix, but lower priority.

7. State After Recovery

# .sdd/state.yaml
recovery:
  date: 2025-01-17
  type: inherited_system | integrity_repair
  
  resolved:
    - "Orphan Design §Caching linked to REQ-005"
    - "Contradiction REQ-003/REQ-005 resolved per DEC-008"
    
  remaining_gaps:
    - id: GAP-001
      type: unknown_rationale
      location: DEC-INHERITED-001
      description: "PostgreSQL selection rationale unknown"
      
  inherited_markers:
    - REQ-INFERRED-001
    - REQ-INFERRED-002
    - DEC-INHERITED-001

Checklist

• All orphans resolved (linked, created parent, or removed)
• All contradictions resolved or escalated
• All broken links fixed
• Version mismatches updated
• Unknown rationale marked explicitly
• Inherited items clearly labeled
• State file updated with recovery status
• Tests re-run after recovery

References

• docs/sdd-guidelines.md §6 Recovery
• docs/sdd-philosophy.md §7 Recovery