AI-DLC Question Format Guide: Machine-Readable Question Structure for Automated Workflows

The AI-DLC question format guide mandates that all workflow inquiries be written to dedicated Markdown files using a strict multiple-choice template with a mandatory [Answer]: tag and an "Other" option always placed last, enabling automated agents to parse responses deterministically without informal chat.

The awslabs/aidlc-workflows repository implements a deterministic AI-Driven Development Life Cycle (AI-DLC) that requires structured communication between agents and users. By following the specifications in aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md, teams create machine-readable question files that eliminate ambiguity and enable automated contradiction detection, ensuring seamless pipeline progression from requirements gathering through deployment.

Core File Requirements and Communication Rules

Dedicated Markdown Files Only

Never ask questions directly in chat. According to the official guide, all inquiries must be persisted to dedicated Markdown files to ensure agents can programmatically access, parse, and validate answers. This rule eliminates the ambiguity of conversational text and enables deterministic workflow automation.

Phase-Based File Naming Convention

Each development phase creates a specific question file following the pattern <phase-name>-questions.md. Common examples include:

• requirements-questions.md
• design-questions.md
• implementation-questions.md

Standardized Question Structure

The AI-DLC format requires strict adherence to a multiple-choice template that guarantees parseability across all workflow phases.

The Multiple-Choice Template

Every question must follow this exact structure:

## Question N

<Clear question text>

A) <Meaningful option 1>
B) <Meaningful option 2>
…
X) Other (please describe after [Answer]: tag below)

[Answer]:

Requirements include:

• At least two meaningful non-filler options
• Sequential lettering (A, B, C...)
• Clear question text in the header

The Mandatory "Other" Option

The "Other" option is mandatory and must always be the final choice (typically the last available letter). This allows users to specify answers outside predefined choices while maintaining the structured format. Users selecting "Other" must describe their response after the [Answer]: tag.

Answer Format and Workflow Integration

The [Answer] Tag Format

Users respond by placing the chosen option letter immediately after the [Answer]: tag. For example:

[Answer]: C

Do not add extra text, punctuation, or explanations on the answer line unless selecting "Other."

Automated Processing Pipeline

After creating the question file, the agent executes the following sequence:

1. Notifies the user to answer the questions
2. Waits for a "done" signal from the user
3. Reads the file programmatically
4. Extracts answers using the [Answer]: tag
5. Validates completeness and format
6. Proceeds to the next phase or generates clarification questions

Validation and Error Handling

Missing or Invalid Answer Detection

When answers are missing or contain invalid option letters, the agent generates a polite request for clarification rather than proceeding with incomplete data or failing silently.

Automated Contradiction Detection

The system automatically analyzes completed question sets for logical inconsistencies. When contradictions are detected (for example, indicating both "new project (greenfield)" and "existing codebase (brownfield)"), the agent creates a <phase-name>-clarification-questions.md file containing targeted multiple-choice questions to resolve the specific conflict.

Practical Examples

Basic Question File Template

The following example demonstrates a properly formatted requirements question file auto-generated by the agent:

# Requirements Clarification Questions

## Question 1

What is the primary user authentication method?

A) Username and password
B) Social media login (Google, Facebook)
C) Single Sign‑On (SSO)
D) Multi‑factor authentication
E) Other (please describe after [Answer]: tag below)

[Answer]:

Completed User Response

When the user selects option C, the file appears as follows:

## Question 1

What is the primary user authentication method?

A) Username and password
B) Social media login (Google, Facebook)
C) Single Sign‑On (SSO)
D) Multi‑factor authentication
E) Other (please describe after [Answer]: tag below)

[Answer]: C

Generated Clarification File

When the agent detects contradictory answers, it generates a clarification file following the same structural rules:

# Requirements Clarification Questions

I detected contradictions in your responses that need clarification:

## Contradiction 1

You indicated "New project (greenfield)" (Q2) but also "Existing codebase (brownfield)" (Q5).

### Clarification Question 1

Which statement best describes the scope of this effort?

A) New greenfield project only
B) Extension of an existing brownfield codebase
C) Both new components and modifications to existing code
D) Other (please describe after [Answer]: tag below)

[Answer]:

Best Practices for Question Design

When authoring questions for the AI-DLC workflow:

• Be specific: Avoid vague options that could be interpreted multiple ways
• Be comprehensive: Cover all likely scenarios with meaningful choices
• Be concise: Eliminate filler options that add no value
• Maintain consistency: Use consistent terminology and formatting across all phases
• Ensure practicality: Design questions that elicit actionable information for the pipeline

Summary

• File-based communication: All questions must be written to phase-specific Markdown files (<phase-name>-questions.md) rather than discussed in chat

• Structured template: Use the standard multiple-choice format with ## Question N headers, lettered options, and a mandatory [Answer]: tag

• Mandatory "Other": Always include an "Other" option as the final choice to capture edge cases

• Machine-readable answers: Respond with only the option letter after [Answer]: unless selecting "Other"

• Automated validation: The system checks for completeness, validates format, and detects logical contradictions through clarification workflows

• Authoritative specification: Reference aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md in the awslabs/aidlc-workflows repository for the complete rule set

Frequently Asked Questions

Why can't questions be asked directly in chat?

The AI-DLC workflow requires deterministic, machine-readable inputs that can be parsed programmatically. Chat messages introduce parsing ambiguity and lack the structured format necessary for automated contradiction detection and pipeline progression. By forcing questions into dedicated Markdown files with strict templates, agents can reliably extract answers and validate completeness without natural language processing errors.

What happens if the "Other" option is omitted?

Omitting the mandatory "Other" option violates the AI-DLC question format specification defined in aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md and will likely cause validation failures when the agent attempts to process the file. The "Other" option serves as a required catch-all for edge cases not covered by predefined choices, ensuring the workflow can handle unexpected scenarios while maintaining structure.

How does the system handle contradictory answers?

When the agent detects logical inconsistencies across responses (such as conflicting project scope declarations), it automatically generates a <phase-name>-clarification-questions.md file containing targeted multiple-choice questions specifically addressing the contradiction. This file follows the same formatting rules as the original question file and must be answered before the workflow can proceed to subsequent phases.

Where is the official AI-DLC question format specification located?

The authoritative specification resides in the awslabs/aidlc-workflows repository at aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md. This document contains the complete rules for file naming, question structure, answer formatting, and best practices for creating machine-readable questions that integrate with the automated development pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}