AI-DLC workflow patterns

Practical patterns for common AI-DLC scenarios. Each section is a self-contained how-to that you can follow step by step.

Quick bug fix workflow

Use this pattern for well-understood bugs where the fix is straightforward and localized.

When to use: Single-file fixes, clear root cause, low risk.

Recommended approach: Use the dedicated /ai-dlc:fix command instead of the full inception-to-construction pipeline.

/ai-dlc:fix 42

Where 42 is the GitHub issue number for the bug.

The fix command follows a TDD-first workflow:

1. Bug characterization -- analyzes affected files, forms a root cause hypothesis, and assesses impact scope
2. Test specification -- generates regression tests, edge case tests, and guard tests before any code changes
3. Builder handoff -- dispatches the fix implementation (to Dr Zero by default, or to the inline code-generator with --no-drzero)

If the bug turns out to require architectural changes or has requirements gaps, the fix command automatically redirects to /ai-dlc:inception with the characterization context preserved.

If you prefer the full pipeline for a bug fix:

/ai-dlc:inception

The workflow planner will detect the low complexity and recommend minimal depth, skipping most optional stages. Inception runs workspace detection, a brief requirements pass, and workflow planning. Construction runs code generation only.

New feature workflow

Use this pattern for adding a new capability to an existing system.

When to use: Moderate complexity, multiple files affected, standard risk.

Step 1: Start inception.

/ai-dlc:inception

Step 2: Answer 12--15 requirements questions at standard depth. Be specific about acceptance criteria and constraints.

Step 3: Review the workflow plan. For a typical feature, expect these stages to execute:

• Inception: workspace detection, requirements, user stories (if user-facing), workflow planning, application design (if new components)
• Construction: functional design, NFR requirements (if performance/security concerns), code generation, build and test

Approve the plan or adjust stage selection.

Step 4: Start construction.

/ai-dlc:construction

Step 5: Review and approve each design stage output before the code generator runs.

Step 6: Review the code generation plan, then approve execution. Inspect generated code and tests.

Step 7: Follow the build-and-test instructions to validate the implementation.

Complex system workflow

Use this pattern for multi-component systems, security-critical changes, or projects with unclear requirements.

When to use: High complexity, multiple services, high risk, compliance requirements.

Step 1: Start inception with the expectation of comprehensive depth.

/ai-dlc:inception

Step 2: Answer 20--30 requirements questions. The questionnaire will cover detailed functional requirements, NFRs across all categories (performance, security, scalability, compliance), tech stack decisions, and acceptance criteria with specific metrics.

Step 3: Review user stories. For complex systems, expect stories for multiple user personas with detailed acceptance criteria.

Step 4: Review the workflow plan. For a complex system, expect all stages to execute including application design and units generation. The system will be decomposed into multiple work units.

Step 5: Start construction.

/ai-dlc:construction

Each unit goes through the full design pipeline: functional design, NFR requirements, NFR design, infrastructure design, then code generation. Each unit completes fully before the next one begins.

Step 6: After all units complete, review the build-and-test instructions which include integration test scenarios across units.

Documentation-only workflow

Use this pattern when the deliverable is documentation rather than application code.

When to use: Creating or improving docs, adding Diataxis structure, writing runbooks.

Step 1: Start inception normally.

/ai-dlc:inception

Step 2: When answering requirements questions, select "Documentation" as the project goal. The questionnaire adapts to ask about documentation scope, target audience, content structure, and integration with the megadoc site instead of asking about APIs, databases, and authentication.

Step 3: Review the workflow plan. The planner should skip most design stages:

• Functional design: SKIP (no business logic)
• NFR requirements: SKIP (no performance/security concerns)
• Infrastructure design: SKIP (no cloud resources)
• Code generation: EXECUTE (generates documentation files)
• Build and test: EXECUTE (validates mkdocs build)

Step 4: The code generator produces documentation files following the Diataxis structure. Review the generated content, adjust as needed, and copy files to their final locations in your repository.

Resuming an interrupted session

AI-DLC maintains state across sessions. If your Claude Code session ends mid-workflow, here is how to pick up where you left off.

Step 1: Check current status.

/ai-dlc:status

This reads aidlc-docs/aidlc-state.md and shows your exact position: which phase, which stage, what has been completed, and what is pending.

Step 2: Resume the appropriate phase.

If you were in inception:

/ai-dlc:inception

The command detects the existing state file and resumes from the last pending stage instead of starting over.

If you were in construction:

/ai-dlc:construction

Construction resumes with the next pending unit or stage.

Step 3: If the state file is corrupted or you want to start fresh, delete it and re-run inception:

rm aidlc-docs/aidlc-state.md

/ai-dlc:inception

Overriding workflow recommendations

The workflow planner makes recommendations, but you have full control.

Adding a stage the planner skipped

At the workflow planning approval gate, say:

"Include Application Design even though you recommended skipping it -- I want to document the component architecture."

The planner will add the stage to the execution plan and proceed.

Removing a stage the planner recommended

At the workflow planning approval gate, say:

"Skip User Stories. I already have clear acceptance criteria in the requirements doc."

The planner will remove the stage and document the override in the audit trail.

Changing the depth level

At any approval gate during inception, say:

"Use minimal depth for faster execution -- this is prototype code."

Or:

"Switch to comprehensive depth -- I realized this is more complex than I thought."

The workflow planner will adjust the remaining stages accordingly.

Reordering units in construction

If the planner recommends executing units in a specific order but you need a different sequence:

"Start with api-service before auth-library -- I need the API endpoints defined first."

The planner will reorder the unit execution sequence.

Working with approval gates

Every critical milestone pauses for your approval. Here is how to work with them effectively.

Approving and continuing

When you are satisfied with a stage's output:

"Approved. Continue."

The workflow advances to the next stage.

Requesting changes

When you want modifications to a stage's output:

"The requirements document is missing error handling requirements for the webhook endpoint. Add requirements for retry logic and dead letter queue handling."

The stage re-executes with your feedback incorporated. You will see the updated output and a new approval gate.

Overriding a stage decision

When you disagree with the workflow planner's recommendation:

"Override: execute NFR Design even though the planner recommended skipping it."

The override is logged in the audit trail with your instruction as the rationale.

Reviewing critical lens findings

When the critical lens agent produces findings at a stage boundary, you disposition each blocker and high finding:

• Accept -- acknowledge the risk with justification (e.g., "Acceptable because we have a compensating control in the API gateway")
• Mitigate -- commit to specific actions (e.g., "Will add input validation in the next code generation pass")
• Defer -- address later with a target (e.g., "Defer to unit-2 infrastructure design stage")
• Reject -- dispute the finding with evidence (e.g., "The API does support this operation -- see docs at ...")

Best practices for requirements Q&A

Getting the most value from the agentic requirements questionnaire:

Be specific over vague. When asked about performance requirements, select "< 100ms p95 latency" over typing "fast." Specific answers produce specific requirements that the code generator can target.

Use custom responses when needed. The multiple-choice options cover common cases, but your situation may be unique. The "Other -- custom response" option lets you provide context the AI would not otherwise have.

Think about edge cases early. When asked about error handling, mention the failure scenarios you care about most. Requirements captured early are cheaper to address than bugs discovered late.

Do not rush through questions. Each question takes seconds to answer but informs downstream stages that take minutes to execute. A thorough 10-minute requirements pass saves hours of rework.

Answer for your actual environment. If you are deploying to Azure with specific constraints (network policies, managed identity, etc.), mention those constraints. The AI cannot infer your deployment environment.

Common pitfalls

Over-engineering simple tasks

Symptom: Running comprehensive depth for a config change or typo fix.

Fix: Trust the workflow planner's depth recommendation for simple changes. If it recommends minimal, it is usually right. Use /ai-dlc:fix for straightforward bug fixes instead of the full pipeline.

Under-engineering complex tasks

Symptom: Forcing minimal depth on a security-critical feature to "save time."

Fix: The time saved during inception is lost many times over during debugging and rework. Use comprehensive depth for:

• Authentication and authorization changes
• Data migration or schema changes
• Multi-component system changes
• Anything involving compliance or regulatory requirements

Skipping approval gates

Symptom: Setting auto_approval: true to move faster.

Fix: Approval gates exist because catching issues early is cheaper than fixing them late. Use auto-approval only for automated testing pipelines, never for production work.

Ignoring the audit trail

Symptom: Not reviewing audit.md after the workflow completes.

Fix: The audit trail is your record of every decision and its rationale. Review it periodically, especially before deploying generated code. It answers questions like "why did we choose this approach?" months after the decision was made.

Not resuming from state

Symptom: Starting a new /ai-dlc:inception when an interrupted session has existing state.

Fix: Always run /ai-dlc:status first. If state exists, the inception command resumes from where you left off instead of starting over.

Integration with git workflows

AI-DLC works well with worktree-based development workflows.

Using worktrees

Create a dedicated worktree for your AI-DLC work:

cd ~/scm/optum-tech-compute/your-repo
git worktree add worktrees/feature-name -b feature/feature-name main
cd worktrees/feature-name

Run AI-DLC inside the worktree. All artifacts (aidlc-docs/) are created in the worktree's working directory, isolated from other branches.

Branching strategy

The aidlc-docs/ directory contains planning artifacts that are useful for code review but may not belong in the final merge. Consider these approaches:

• Include in PR: Keep aidlc-docs/ in the branch for reviewers to see the requirements, design decisions, and audit trail. Remove or .gitignore before merging to main.
• Separate docs branch: Keep aidlc-docs/ on a separate branch for archival. Merge only the generated code to main.
• Always commit: Some teams keep all AI-DLC artifacts in the repository permanently for traceability. Add them to the docs/ directory if they have long-term value.

Committing generated code

After construction completes:

1. Review all generated files in aidlc-docs/construction/{unit}/code/
2. Copy or move them to the appropriate locations in your repository
3. Run your project's test suite to validate
4. Commit the production code with a descriptive message referencing the AI-DLC workflow
5. Optionally commit the aidlc-docs/ artifacts in a separate commit for audit purposes