User Clarification Guidelines

Guidelines for creating and managing clarification files when AI assistants encounter ambiguities during task execution.

---

Purpose

When executing complex tasks, AI assistants may encounter ambiguities that require user input. Rather than:

Making arbitrary decisions silently
Stopping at the first ambiguity
Asking questions one at a time

The assistant should:

Collect all ambiguities before stopping
Document decisions made for user confirmation
Create a structured clarification file with all questions
Pause once to minimize workflow interruption

---

When to Create a Clarification File

Required Triggers

Create a clarification file when:

Trigger	Example
Multiple valid interpretations	"Process files" - alphabetically? by dependency?
Missing specification	No error handling defined
Scope unclear	"Support nesting" - to what depth?
Business logic decision	Should X override Y or merge?
Conflicting requirements	Rule A says X, Rule B implies Y
Performance tradeoff	Fast but approximate vs. slow but exact

Optional Triggers

Consider a clarification file for:

Edge cases not covered in specification
Assumptions that significantly affect outcome
Design choices with long-term implications

Skip Clarification When

Default is obvious and low-impact
Specification is clear enough to proceed
Change can be easily reversed later

---

Clarification File Structure

File Naming

{YYYYMMDD_HHMMSS}_{task_name}_clarifications.md

The date/time prefix ensures files appear in chronological order when sorted alphabetically in the folder.

Component	Format	Description
Date	`YYYYMMDD`	Year, month, day (e.g., `20260113`)
Time	`HHMMSS`	Hours, minutes, seconds in 24h format (e.g., `104500`)
Task name	`lowercase_with_underscores`	Descriptive name of the task

Examples:

20260113_104500_build_system_clarifications.md
20260113_142030_mode_resolver_clarifications.md
20260114_091500_api_refactor_clarifications.md

File Location

Clarification files are placed in the _ai/clarifications/ folder:

Scope	Location
Project-specific	`{project}/_ai/clarifications/`
Workspace-wide	`_ai/clarifications/` (workspace root)

Important: Copilot must inform the user when a clarification file has been created, including the file path and a summary of the questions.

Processing Workflow

┌─────────────────────┐     ┌─────────────────┐     ┌─────────────────────────────────────┐
│ Create file in      │     │ User provides   │     │ Move file to                        │
│ _ai/clarifications/ │ ──► │ answers         │ ──► │ _ai/clarifications_processed/       │
└─────────────────────┘     └─────────────────┘     └─────────────────────────────────────┘

Phase	File Location	Status
Created	`_ai/clarifications/{name}_clarifications.md`	AWAITING USER RESPONSE
Answered	(same location)	User has filled in answers
Processed	`_ai/clarifications_processed/{name}_clarifications.md`	RESOLVED

After incorporating the user's answers:

1. Update the clarification file status to RESOLVED 2. Add resolution date and summary 3. Move the file from _ai/clarifications/ to _ai/clarifications_processed/

Complete Template

# Clarification Request: {Task Name}

## Status: AWAITING USER RESPONSE

**Created:** {date}
**Task:** {brief description of what was being attempted}
**Blocked:** Yes - awaiting answers to proceed

---

## Summary

{2-3 sentences explaining why clarification is needed}

**Questions:** {N} questions requiring your input
**Decisions:** {M} decisions made by Copilot for your confirmation

---

## Questions Requiring Your Input

### Q1: {Short descriptive title}

**Context:**
{Why this question arose - what was being processed, what ambiguity was found}

**Question:**
{The specific question, clearly stated}

**Options:**

| Option | Description | Implications |
| ------ | ----------- | ------------ |
| A | {description} | {what this choice means for implementation} |
| B | {description} | {what this choice means for implementation} |
| C | {description} | {what this choice means for implementation} |

**Copilot's Recommendation:** Option {X}

**Reasoning:** {Why this option was suggested}

**Your Answer:** ________________

---

### Q2: {Short descriptive title}

**Context:**
{context}

**Question:**
{question}

**Options:**

| Option | Description | Implications |
| ------ | ----------- | ------------ |
| A | {description} | {implications} |
| B | {description} | {implications} |

**Copilot's Recommendation:** Option {X}

**Reasoning:** {reasoning}

**Your Answer:** ________________

---

## Decisions Made by Copilot

The following decisions were made during analysis. Please review and confirm
or override each decision.

| # | Decision | Copilot Choice | Reasoning | Confirmed? |
| - | -------- | -------------- | --------- | ---------- |
| D1 | {what was decided} | {choice made} | {why} | Yes / No / Override: ___ |
| D2 | {what was decided} | {choice made} | {why} | Yes / No / Override: ___ |
| D3 | {what was decided} | {choice made} | {why} | Yes / No / Override: ___ |

---

## Assumptions

The following assumptions are being made. Flag any that are incorrect:

- [ ] {Assumption 1}
- [ ] {Assumption 2}
- [ ] {Assumption 3}

---

## How to Respond

1. **Answer each question** in the "Your Answer" field
2. **Review decisions** in the table and mark Confirmed (Yes/No/Override)
3. **Check assumptions** and uncheck any that are wrong
4. **Save this file**
5. **Continue with prompt:**

Continue the task using the answers in {filename}_clarifications.md


---

## After Resolution

Once answers are provided, this file will be updated with:

- Status changed to: RESOLVED
- Resolution date
- Summary of answers incorporated

This file serves as documentation of decisions made during implementation.

---

## Best Practices

### Question Quality

| Do | Don't |
| -- | ----- |
| Ask specific, answerable questions | Ask vague or open-ended questions |
| Provide concrete options | Leave options undefined |
| Explain implications of each choice | Present options without context |
| Include your recommendation | Make user decide without guidance |
| Group related questions | Scatter related questions throughout |

### Question Wording

**Good:**

> "Should mode blocks be processed before or after placeholder substitution?"
>
> - Before: Placeholders in excluded blocks are never evaluated
> - After: All placeholders are evaluated, then blocks are removed

**Poor:**

> "What should happen with mode blocks and placeholders?"

### Minimizing Questions

Before adding a question, ask:

1. Is there a reasonable default?
2. Can this be easily changed later?
3. Does the specification imply an answer?
4. Is this truly blocking?

If yes to any, make the decision and document it in the "Decisions Made" section instead.

### Decision Documentation

When Copilot makes a decision without asking:

#	Decision	Copilot Choice	Reasoning	Confirmed?
D1	Error message format	Include file path and line number	Helps debugging	Yes / No
D2	Default mode when unspecified	"default"	Matches existing convention	Yes / No


---

## Workflow Integration

### Standard Response Pattern

When a prompt contains multiple TODOs and ambiguities are found:

I started working on your {N} TODOs and found {M} ambiguities that need clarification before I can proceed.

I've created {task}_clarifications.md with: - {X} questions requiring your input - {Y} decisions I made that need your confirmation

Completed before stopping: - TODO 1: {description} ✓ - TODO 2: Partial - stopped at {point}

Blocked: - TODO 3-N: Waiting for clarification

Please review the clarification file and provide answers, then continue with: "Continue using the answers in {task}_clarifications.md"


### Continuation After Answers

When user provides answers:

1. Read the clarification file
2. Extract answers and confirmed decisions
3. Apply any overrides
4. Continue with remaining TODOs
5. Update clarification file status to RESOLVED

### Multiple Clarification Rounds

If new ambiguities are found after initial answers:

1. Update existing clarification file (don't create new one)
2. Add new questions at the end
3. Keep resolved questions marked as answered
4. Change status back to AWAITING USER RESPONSE

---

## Examples

### Example: Build System Clarification

Clarification Request: Build System Implementation

Status: AWAITING USER RESPONSE

Created: 2026-01-13 Task: Implementing workspace build system from specification Blocked: Yes - awaiting answers to proceed

---

Summary

While implementing the build system, I found 3 ambiguities in the specification regarding mode processing order, error handling strategy, and file watching behavior.

Questions: 3 questions requiring your input Decisions: 2 decisions made by Copilot for your confirmation

---

Questions Requiring Your Input

Q1: Mode Block Processing Order

Context: The specification describes both mode block resolution and placeholder substitution, but doesn't specify which happens first.

Question: Should mode blocks be processed before or after placeholder substitution?

Options:

Option	Description	Implications
A	Mode blocks first	Placeholders in excluded blocks are never evaluated
B	Placeholders first	All placeholders evaluated, then blocks removed
C	Interleaved	Mode blocks resolved, then placeholders, per-block

Copilot's Recommendation: Option A

Reasoning: Processing mode blocks first is more efficient (less work on excluded content) and safer (no errors from placeholders in excluded blocks).

Your Answer: ________________

---

Q2: Error Handling for Missing Files

Context: When a referenced file (import, tomplate) doesn't exist, the specification doesn't define behavior.

Question: How should missing file references be handled?

Options:

Option	Description	Implications
A	Fatal error	Build stops immediately with error message
B	Warning + skip	Log warning, continue without the file
C	Warning + default	Log warning, use empty/default content

Copilot's Recommendation: Option A

Reasoning: Missing files are likely configuration errors that should be fixed rather than silently ignored.

Your Answer: ________________

---

Decisions Made by Copilot

#	Decision	Copilot Choice	Reasoning	Confirmed?
D1	YAML parser library	`yaml` package	Standard Dart YAML package	Yes / No
D2	Output file encoding	UTF-8	Universal compatibility	Yes / No

---

Assumptions

[ ] All YAML files use UTF-8 encoding
[ ] Maximum nesting depth for mode blocks is 10
[ ] File paths are relative to workspace root unless absolute

---

How to Respond

1. Answer each question in the "Your Answer" field 2. Review decisions and mark Confirmed 3. Check assumptions for any that are incorrect 4. Save this file 5. Continue with: !continue


---

## Quick Reference

### Clarification File Checklist

Before creating a clarification file:

- [ ] Collected ALL ambiguities (don't stop at first one)
- [ ] Documented decisions made by Copilot
- [ ] Provided options with implications for each question
- [ ] Included recommendation for each question
- [ ] Listed assumptions being made
- [ ] Included clear "how to respond" instructions

### Question Categories

| Category | Example Question |
| -------- | ---------------- |
| **Order** | Should X happen before or after Y? |
| **Scope** | Should this apply to A, B, or both? |
| **Default** | What value should be used when unspecified? |
| **Error** | Should errors fail fast or be collected? |
| **Conflict** | When X and Y conflict, which takes precedence? |
| **Limit** | What is the maximum depth/size/count? |

### Status Values

| Status | Meaning |
| ------ | ------- |
| AWAITING USER RESPONSE | Questions need answers |
| RESOLVED | All questions answered, work can continue |
| SUPERSEDED | Replaced by newer clarification file |