Adds 2 units and docs for unit 3. nfr-requirements plan
This commit is contained in:
@@ -0,0 +1,171 @@
|
||||
# Gap Report: Functional Design Questions Placed in Chat Without [Answer] Tags
|
||||
|
||||
**Gap ID**: gap-006
|
||||
**Reported**: 2026-06-29
|
||||
**Reporter**: User (via master-cms-module Unit 3 Functional Design session)
|
||||
**Skill affected**: `aidlc-workflow`
|
||||
**Rule files affected**:
|
||||
- `.aidlc-rule-details/construction/functional-design.md` — Step 3, Step 4, Step 5
|
||||
- `.aidlc-rule-details/common/question-format-guide.md` — "Never Ask Content Questions in Chat"
|
||||
|
||||
---
|
||||
|
||||
## Problem Description
|
||||
|
||||
During Unit 3 (`frontend-cms-page`) Functional Design, the agent violated two mandatory rules simultaneously:
|
||||
|
||||
### Violation 1 — Content questions placed in chat
|
||||
|
||||
The agent repeated all 5 clarification questions **directly in the chat message** at the end of its response. This violates `question-format-guide.md`:
|
||||
|
||||
> **CRITICAL**: You must NEVER ask **content/domain questions** directly in the chat. These MUST be placed in dedicated question files using the `[Answer]:` tag format.
|
||||
|
||||
### Violation 2 — Plan file had no `[Answer]:` tags and no `Other` option
|
||||
|
||||
The agent created `frontend-cms-page-functional-design-plan.md` with questions in a `## Clarifying Questions` section, but:
|
||||
- Every question was missing the mandatory `[Answer]:` tag
|
||||
- Every question was missing the mandatory `Other` option as the last choice
|
||||
- The file was labeled a "plan" but acted as a question file without meeting question file requirements
|
||||
|
||||
From `functional-design.md` Step 3 Definition of Done:
|
||||
> - [ ] Every question has a `[Answer]:` tag
|
||||
> - [ ] The final option is `Other`
|
||||
|
||||
From `question-format-guide.md`:
|
||||
> `Other` is MANDATORY as the LAST option for every question
|
||||
|
||||
### Violation 3 — Chat notification message was too long and repeated question content
|
||||
|
||||
`functional-design.md` Step 5 prescribes this exact short format:
|
||||
|
||||
```markdown
|
||||
# 📝 Functional Design Plan Ready - [unit-name]
|
||||
|
||||
I've created a functional design plan with questions at:
|
||||
`aidlc-docs/features/{feature-slug}/construction/plans/[unit-name]-functional-design-plan.md`
|
||||
|
||||
Please answer each question by filling in your choice after the `[Answer]:` tag in the file.
|
||||
Let me know in chat when you're done.
|
||||
```
|
||||
|
||||
Instead, the agent produced a long chat message with headers, all 5 questions restated in full with options (Q1–Q5), and no `[Answer]:` pointers — making it indistinguishable from a content interaction rather than a process notification.
|
||||
|
||||
---
|
||||
|
||||
## Observed Behavior
|
||||
|
||||
The agent:
|
||||
1. Created `frontend-cms-page-functional-design-plan.md` with questions missing `[Answer]:` tags and `Other` options
|
||||
2. Posted a lengthy chat message restating all 5 questions with options (A/B/C) directly in chat
|
||||
3. Did NOT produce a separate `*-questions.md` file following the question-format-guide format
|
||||
|
||||
The chat message looked like other phases' content discussions rather than a process notification pointing to a file.
|
||||
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
|
||||
Two likely causes:
|
||||
|
||||
**A) The plan file format ambiguity**: The construction plan file (used to track steps) and the question file (used to collect answers) were conflated into one file. The agent embedded questions in the plan instead of creating a separate dedicated question file (e.g. `frontend-cms-page-fd-questions.md`).
|
||||
|
||||
**B) Step 5 format not enforced strongly enough**: `functional-design.md` Step 5 says "Present a brief chat message" but does not use strong directive language (`CRITICAL`, `MANDATORY`) to prohibit reproducing question content in chat. The agent defaulted to showing the questions for "helpfulness."
|
||||
|
||||
---
|
||||
|
||||
## Impact
|
||||
|
||||
- User receives questions in chat instead of in a file → cannot fill in `[Answer]:` tags
|
||||
- No audit trail of answers in the file system
|
||||
- Chat message looks inconsistent with other phases (FD questions in previous units had the correct format)
|
||||
- User is confused about where and how to answer the questions
|
||||
|
||||
---
|
||||
|
||||
## Suggested Fix
|
||||
|
||||
### Fix 1 — Separate plan file from question file
|
||||
|
||||
In `functional-design.md` Step 3–4, make explicit that:
|
||||
- The **plan file** (`{unit-name}-functional-design-plan.md`) contains only step checkboxes
|
||||
- A **separate question file** (`{unit-name}-fd-questions.md`) is always created alongside it, following `question-format-guide.md` exactly
|
||||
- The plan file MUST NOT contain `[Answer]:` questions inline
|
||||
|
||||
**Current Step 4 (ambiguous)**:
|
||||
```markdown
|
||||
### Step 4: Store Plan
|
||||
- Save as `aidlc-docs/features/{feature-slug}/construction/plans/{unit-name}-functional-design-plan.md`
|
||||
- Include all [Answer]: tags for user input
|
||||
```
|
||||
|
||||
**Proposed Step 4 (explicit)**:
|
||||
```markdown
|
||||
### Step 4: Store Artifacts
|
||||
- Save plan as `aidlc-docs/features/{feature-slug}/construction/plans/{unit-name}-functional-design-plan.md`
|
||||
- Contains ONLY the step checklist — NO questions or [Answer] tags
|
||||
- Save questions as `aidlc-docs/features/{feature-slug}/construction/plans/{unit-name}-fd-questions.md`
|
||||
- Follows `common/question-format-guide.md` exactly
|
||||
- MANDATORY: Every question has `[Answer]:` tag and `Other` as final option
|
||||
- Validate against question-format-guide.md Definition of Done before saving
|
||||
```
|
||||
|
||||
### Fix 2 — Add CRITICAL language to Step 5
|
||||
|
||||
**Current Step 5**:
|
||||
```markdown
|
||||
### Step 5: Notify User (in chat)
|
||||
Present a brief chat message pointing the user to the plan file:
|
||||
```
|
||||
|
||||
**Proposed Step 5**:
|
||||
```markdown
|
||||
### Step 5: Notify User (in chat)
|
||||
**CRITICAL**: Present ONLY this short process notification. Do NOT reproduce questions in chat. Do NOT add extra explanation.
|
||||
```
|
||||
|
||||
Then keep the existing template as-is, but add:
|
||||
|
||||
```markdown
|
||||
**PROHIBITED**: Repeating question content in the chat notification. The questions are in the file — do not summarize or restate them here.
|
||||
```
|
||||
|
||||
### Fix 3 — Add self-validation step after question file creation
|
||||
|
||||
Add a checkpoint between Step 3 and Step 4:
|
||||
|
||||
```markdown
|
||||
### Step 3b: Validate Question File
|
||||
Before saving, verify the question file against `question-format-guide.md` Definition of Done:
|
||||
- [ ] Every question is multiple choice with lettered options (A, B, C…)
|
||||
- [ ] Every question has `Other` as the final option
|
||||
- [ ] Every question has a `[Answer]:` tag immediately after the options
|
||||
- [ ] No question appears in the plan file or chat
|
||||
If any check fails: fix the file before proceeding to Step 4.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- Skill: `C:\Users\Bryan\.claude\skills\aidlc-workflow-workspace\skill-snapshot\`
|
||||
- Rule: `.aidlc-rule-details/construction/functional-design.md` — Steps 3, 4, 5
|
||||
- Rule: `.aidlc-rule-details/common/question-format-guide.md` — "Never Ask Content Questions in Chat", "Definition of Done"
|
||||
|
||||
---
|
||||
|
||||
## Immediate Workaround (current session)
|
||||
|
||||
The agent must now:
|
||||
1. **Delete** the plan file's embedded questions section (or rewrite it as a proper question file)
|
||||
2. **Create** `aidlc-docs/features/master-cms-module/construction/plans/frontend-cms-page-fd-questions.md` with all 5 questions in correct format (multiple-choice + `Other` + `[Answer]:` tag)
|
||||
3. **Send** only the prescribed short Step 5 notification in chat
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria for Fix
|
||||
|
||||
- [ ] `functional-design.md` Step 4 distinguishes plan file (checklist only) from question file (answers)
|
||||
- [ ] `functional-design.md` Step 5 has CRITICAL/PROHIBITED language against reproducing questions in chat
|
||||
- [ ] A Step 3b self-validation checkpoint is added before saving question files
|
||||
- [ ] After the fix, FD question files always contain `[Answer]:` tags and `Other` options
|
||||
- [ ] After the fix, chat notification for FD is always the short 4-line format from the template
|
||||
Reference in New Issue
Block a user