How to Create Valid Multiple-Choice Questions for AI-DLC

AI-DLC requires multiple-choice questions to be stored in markdown files ending with -questions.md, using a strict format with lettered options (A, B, C...), a mandatory "Other" option as the final choice, and an [Answer]: tag for automated response extraction.

The AWS Labs AI-DLC (AI-Driven Development Lifecycle) system automates software development workflows by parsing structured human inputs. According to the question-format-guide.md in the awslabs/aidlc-workflows repository, every query must follow a deterministic markdown structure that the engine validates during the Inception phase.

File Naming and Storage Location

Every question file must reside in the aidlc-docs/ directory and use a descriptive name ending with the -questions.md suffix.

• Valid names: requirements-questions.md, design-questions.md, security-questions.md
• Invalid names: questions.md, reqs.txt, inception_questions.markdown

This naming convention allows the workflow engine to locate and ingest the correct files automatically for each development phase.

Required Markdown Structure

The Header Block

Start the file with a top-level heading that describes the purpose of the questionnaire.

# Requirements Clarification Questions

Please answer the following questions to help clarify the project requirements.

The Question Block Format

Each question must follow this exact pattern:

## Question 1

What authentication method should the API use?

A) API key
B) OAuth 2.0 (Authorization Code flow)
C) JWT with custom claims
D) Other (please describe after [Answer]: tag below)

[Answer]: 

Key structural requirements:

• Use ## Question <N> as the subheading

• Present options as capital letters followed by a closing parenthesis (A), B), etc.)

• Place the [Answer]: tag on its own line after the final option

• Leave the answer line blank for users to fill in (e.g., [Answer]: B)

Option Constraints and Quality Standards

AI-DLC enforces strict rules on the number and nature of options to ensure unambiguous parsing.

Option Count Rules:

• Minimum: 2 meaningful options + "Other"
• Typical: 3–4 options + "Other"
• Maximum: 5 options + "Other"

Option Quality Requirements:

• Options must be mutually exclusive to prevent ambiguous selections
• Content must be realistic and concise to enable clear model mapping
• The "Other" option must always be the last entry and labeled exactly as "Other"

Violating these constraints causes the workflow stage to halt until the format is corrected.

Answer Format and Validation

Users submit responses by placing the chosen letter after the [Answer]: tag.

Valid response:

[Answer]: B

Invalid responses that trigger error handling:

• Missing answer (empty after colon) → Engine prompts user to complete
• Invalid letter (not matching any option) → Engine requests a valid option letter
• Ambiguous answer (multiple letters or text without "Other" selection) → Engine requests a single letter choice

These validation rules are enforced by the workflow engine to prevent silent failures and ensure deterministic hand-offs between human and AI agents.

Complete Implementation Examples

Example 1: Requirements Clarification File

Create aidlc-docs/requirements-questions.md:

# Requirements Clarification Questions

Please answer the following questions to help clarify the project requirements.

## Question 1

What authentication method should the API use?

A) API key
B) OAuth 2.0 (Authorization Code flow)
C) JWT with custom claims
D) Other (please describe after [Answer]: tag below)

[Answer]: 

## Question 2

What is the preferred deployment environment?

A) AWS Lambda
B) Kubernetes (EKS)
C) EC2 instances
D) Other (please describe after [Answer]: tag below)

[Answer]: 

Example 2: Bash Script Generation

Generate the file programmatically:

cat > aidlc-docs/requirements-questions.md <<'EOF'

# Requirements Clarification Questions

## Question 1

What authentication method should the API use?

A) API key
B) OAuth 2.0 (Authorization Code flow)
C) JWT with custom claims
D) Other (please describe after [Answer]: tag below)

[Answer]:
EOF

Example 3: Python Validation Script

Parse and validate answers using the exact regex pattern the engine employs:

import re
import pathlib

def parse_questions(path):
    text = pathlib.Path(path).read_text()
    # Matches the [Answer]: tag format including empty responses

    answers = re.findall(r'\[Answer\]:\s*(\w?)', text)
    if '' in answers:
        raise ValueError("Some questions are unanswered.")
    return answers

answers = parse_questions('aidlc-docs/requirements-questions.md')
print("Collected answers:", answers)

Workflow Integration Process

The AI-DLC engine processes question files through a four-step deterministic hand-off:

1. Creation: Generate the *-questions.md file in aidlc-docs/
2. Prompting: Present the file to the user with instructions to fill in answer letters
3. Synchronization: Wait for a completion signal (e.g., "done", "finished")
4. Validation: The engine reads the file, checks for completeness, detects contradictions, and proceeds to the next phase

This process is implemented in the workflow engine according to the specifications in aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md. A working example of a fully populated question file appears in scripts/aidlc-evaluator/test_cases/all-stages/golden-aidlc-docs/aidlc-docs/inception/requirements/requirement-verification-questions.md.

Summary

• Store question files in aidlc-docs/ with the -questions.md suffix
• Structure each question with lettered options (A), B), etc.) and a mandatory "Other" option last
• Include exactly 2 to 5 meaningful options plus "Other", ensuring they are mutually exclusive and concise
• Place the [Answer]: tag immediately after each question block for automated extraction
• Expect the engine to validate responses during the Inception phase and halt on missing or invalid answers

Frequently Asked Questions

What is the maximum number of options allowed in an AI-DLC multiple-choice question?

The format permits a maximum of 5 meaningful options plus the mandatory "Other" option. Exceeding this limit causes the workflow engine to reject the file during the validation phase. The minimum required is 2 options plus "Other".

Is the "Other" option mandatory for all AI-DLC questions?

Yes. Every question must include "Other" as the final option labeled exactly as "Other (please describe after [Answer]: tag below)". This provides a required fallback when none of the concrete options apply, ensuring the workflow can handle edge cases without breaking.

How does the AI-DLC workflow detect incomplete answers?

During the validation step, the engine parses the [Answer]: tag using regex pattern matching. If the tag is empty, contains an invalid letter (not corresponding to A-X), or contains multiple characters (indicating ambiguity), the workflow triggers specific error handlers that prompt the user to provide a single valid letter choice.

Can I nest markdown formatting inside the question text?

While the question-format-guide.md specifies the structural requirements for the question block, it emphasizes that options must be realistic and concise. Complex formatting within option text is not recommended because the engine relies on clear, unambiguous parsing of the [Answer]: tag and option letters. Standard markdown in the header or question description is acceptable.

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