DIDP Methodology Guide

This guide walks you through using DIDP (Deterministic Iterative Development Protocol) in your projects. By the end, you’ll understand how to set up DIDP, run iterations, and handle common scenarios.

What is DIDP?

DIDP is a phase-based development protocol designed for AI-assisted development. It solves a critical problem: AI assistants lose context between sessions.

Traditional development assumes continuous human memory. But when you’re working with an AI assistant that may:

  • Hit context limits and need compaction
  • Crash or disconnect
  • Be a different instance next session

…you need a way to restore state from artifacts, not memory.

DIDP provides:

  • Deterministic phases with clear entry/exit criteria
  • Artifact-first development where documents override memory
  • Compaction-safe workflows that survive context loss
  • Clear authority hierarchy when conflicts arise

Quick Start

1. Create Your Iteration State

Create iteration_state.yaml in your project root:

iteration:
  id: "my-first-iteration"
  goal: "Build feature X"
  created_at: "2025-01-15"

phase:
  name: planning
  entered_at: "2025-01-15"
  auto_advance: true
  locked: false

exit_criteria:
  - criterion: "Requirements documented"
    satisfied: false
  - criterion: "Scope agreed"
    satisfied: false

artifacts: []

handoff_notes:
  summary: "Starting new iteration"
  decisions_made: []
  risks_identified: []
  next_recommended_action: "Define requirements for feature X"

2. Add the Workflow Contract

Copy the Workflow Contract to docs/workflow_contract.md. This tells AI assistants how to behave.

3. Create a Bootstrap Prompt

Create prompts/bootstrap.txt:

You are operating under DIDP.

MANDATORY FIRST ACTIONS:
1. Read docs/workflow_contract.md
2. Read iteration_state.yaml
3. Identify current phase
4. Resume from handoff_notes.next_recommended_action

If any document is missing or inconsistent, STOP and report.

4. Start Your Session

Begin each AI session with the bootstrap prompt. The assistant will:

  1. Read the workflow contract
  2. Load current iteration state
  3. Understand what phase you’re in
  4. Resume from where you left off

The Phase Model

Overview

planning → analysis → spec_lock → implementation → testing → archive → merge → complete

Each phase has:

  • Purpose: What you’re trying to achieve
  • Allowed actions: What you can do
  • Exit criteria: How you know you’re done
  • Conversation style: How interactive it should be

Planning Phase

Purpose: Open exploration and scope definition

Allowed:

  • Brainstorming
  • Requirements gathering
  • Architecture discussions
  • Scope changes

Exit when:

  • Requirements documented
  • Scope agreed
  • Initial plan exists

Conversation: Back-and-forth expected

# Example exit criteria for planning
exit_criteria:
  - criterion: "Requirements documented in requirements.md"
    satisfied: true
  - criterion: "Scope agreed with stakeholder"
    satisfied: true
  - criterion: "High-level approach selected"
    satisfied: true

Analysis Phase

Purpose: Validate assumptions from planning

Allowed:

  • Feasibility checks
  • Risk assessment
  • Clarifying questions
  • Prototyping

Not Allowed:

  • Scope changes (triggers replan)

Exit when:

  • Assumptions validated
  • Risks documented
  • Approach confirmed feasible

Conversation: Clarifying questions OK

Spec Lock Phase

Purpose: Freeze the specification

Allowed:

  • Finalizing requirements
  • Creating implementation plan
  • Writing test plan

Not Allowed:

  • Re-opening planning discussions
  • Scope changes

Exit when:

  • Specification frozen
  • Implementation plan complete
  • Test plan complete

Conversation: Structured finalization only

Implementation Phase

Purpose: Execute the plan

Allowed:

  • Writing code
  • Creating artifacts
  • Execution-focused clarifications

Not Allowed:

  • Scope discussions
  • Requirement changes

Exit when:

  • All planned work complete
  • Code committed

Conversation: Minimal, execution-focused

Testing Phase

Purpose: Verify the implementation

Allowed:

  • Running tests
  • Defect documentation
  • Bug fixes

Not Allowed:

  • Feature additions
  • Scope changes

Exit when:

  • All tests pass
  • Defects addressed or documented

Conversation: Defect-focused only

Archive, Merge, Complete

These are mechanical phases:

  • Archive: Preserve iteration state
  • Merge: Integrate to main branch
  • Complete: Write retrospective

Handling Common Scenarios

Session Ends Mid-Work

  1. AI updates iteration_state.yaml:

    handoff_notes:
  summary: "Implemented 3 of 5 endpoints"
  next_recommended_action: "Complete remaining endpoints: /users, /orders"

  2. Commit the state file

  3. Next session starts with bootstrap prompt, reads state, continues

AI Hits Context Limit

Same as above. DIDP is designed for this. The artifacts contain everything needed to resume.

Need to Change Scope During Analysis

If analysis reveals planning assumptions are wrong:

analysis_outcome:
  replan_required: true
  reason: "API we planned to use is deprecated. Need alternative approach."

This triggers the replan protocol:

  1. Phase resets to planning
  2. Reason is documented
  3. Planning resumes with new information

Conflicting Information

Use the authority hierarchy:

  1. iteration_state.yaml wins
  2. Then workflow_contract.md
  3. Then phase artifacts
  4. Then git state
  5. Conversation is lowest authority

Something Feels Wrong

If the AI is unsure:

  • It should STOP
  • Ask for clarification
  • Never guess or proceed with uncertainty

Best Practices

Update State Frequently

Don’t wait until end of session:

# After each meaningful progress
handoff_notes:
  summary: "Completed database schema design"
  decisions_made:
    - "Using PostgreSQL instead of MongoDB"
  next_recommended_action: "Implement User model"

Commit State Changes

git add iteration_state.yaml
git commit -m "Progress: completed database schema"

Use Clear Exit Criteria

Bad:

exit_criteria:
  - criterion: "Done with requirements"
    satisfied: false

Good:

exit_criteria:
  - criterion: "All user stories written in requirements.md"
    satisfied: false
  - criterion: "Each story has acceptance criteria"
    satisfied: false
  - criterion: "Stories reviewed by product owner"
    satisfied: false

Trust Artifacts Over Memory

If an AI assistant says “I remember we decided X” but iteration_state.yaml says Y, trust Y.

Troubleshooting

”I don’t know what phase we’re in”

Read iteration_state.yaml. The phase.name field is authoritative.

”Exit criteria seem wrong”

Update them in iteration_state.yaml. They’re not immutable until spec_lock.

”AI keeps doing out-of-phase work”

Re-emphasize the workflow contract. The AI should refuse out-of-phase requests.

”Session recovery isn’t working”

Check:

  1. Is iteration_state.yaml committed?
  2. Does bootstrap prompt include mandatory actions?
  3. Is handoff_notes.next_recommended_action clear?

Next Steps