Finishes functional design for unit 0 (back-end changes before front-end work)

2026-06-18 21:40:45 +02:00
parent 9e49489f7e
commit 53a307cdbd
14 changed files with 1065 additions and 4 deletions
@@ -0,0 +1,121 @@
+# Gap Report: Completion Messages Missing AI Summary
+
+**Gap ID**: gap-002
+**Reported**: 2026-06-16
+**Reporter**: User (via cms-frontend Units Generation completion)
+**Skill affected**: `aidlc-workflow`
+**Rule files affected**:
+- `.aidlc-rule-details/inception/units-generation.md` — Step 16
+- `.aidlc-rule-details/inception/requirements-analysis.md` — Step 9
+- `.aidlc-rule-details/inception/application-design.md` — Step 12
+- `.aidlc-rule-details/inception/user-stories.md` — Step 20
+- `.aidlc-rule-details/inception/workflow-planning.md` — Step 9
+- (potentially all other stage completion messages)
+
+---
+
+## Problem Description
+
+All stage completion messages in the aidlc-workflow skill follow a 3-part structure:
+
+1. **Completion Announcement** (mandatory)
+2. **AI Summary** — described as "optional" in the rule files
+3. **Formatted Workflow Message** with REVIEW REQUIRED + WHAT'S NEXT (mandatory)
+
+The AI Summary part is described as:
+> "AI Summary (optional): Provide structured bullet-point summary of..."
+
+Because the word **"optional"** appears in the rule file, the AI model frequently omits the AI Summary section entirely. This results in completion messages that consist only of a heading and two action options, with no information about:
+- What was created or changed
+- Which files to review and why
+- Key decisions that were made
+- Counts, scopes, or metrics of the work done
+
+### Observed Behavior
+```markdown
+## 🔧 Units Generation Complete
+
+> **📋 REVIEW REQUIRED:**
+> ...
+
+> **🚀 WHAT'S NEXT?**
+> 🔧 Request Changes
+> ✅ Approve & Continue
+```
+
+### Expected Behavior
+```markdown
+## 🔧 Units Generation Complete
+
+Units generation has decomposed the CMS frontend into 7 units:
+- **Unit 0** (Backend Prerequisites): CORS policy, httpOnly cookie support in AuthController
+- **Unit 1** (Project Scaffold): Vite + TanStack Router + shadcn/ui + ApiClient + AuthContext
+- ...
+- **20/20 stories** assigned across all units
+- **3 artifacts** generated: unit-of-work.md, unit-of-work-dependency.md, unit-of-work-story-map.md
+
+> **📋 REVIEW REQUIRED:**
+> ...
+```
+
+---
+
+## Root Cause
+
+The word **"optional"** in the AI Summary description is being treated as a literal skip instruction by the model. The intent is that it is "optional" in format (not mandatory to follow a rigid template), but the **presence of a summary is mandatory** for usability.
+
+---
+
+## Impact
+
+- Users cannot determine what was done without opening multiple files
+- The review step becomes ineffective because users don't know which files changed or why
+- The workflow feels abrupt and opaque after each stage
+- User trust in the workflow decreases when completions seem empty
+
+---
+
+## Suggested Fix
+
+Replace the word "optional" in all AI Summary descriptions with language that makes the summary **required but flexible in format**. For example:
+
+**Current** (all affected rule files):
+```markdown
+**AI Summary** (optional): Provide structured bullet-point summary of...
+```
+
+**Proposed fix**:
+```markdown
+**AI Summary** (mandatory, flexible format): Provide a structured bullet-point summary of what was created, changed, or decided during this stage. Include:
+- Key artifacts created (names, not full paths)
+- Counts or metrics (e.g. "20/20 stories assigned", "7 units defined")
+- Key decisions made
+- Anything the user needs to know to do a meaningful review
+DO NOT include workflow instructions, file paths, or "please review" language here.
+```
+
+---
+
+## Affected Rule Files (all need the same fix)
+
+| Rule File | Section |
+|-----------|---------|
+| `inception/units-generation.md` | Step 16 — AI Summary |
+| `inception/requirements-analysis.md` | Step 9 — AI Summary |
+| `inception/application-design.md` | Step 12 — AI Summary |
+| `inception/user-stories.md` | Step 20 — AI Summary |
+| `inception/workflow-planning.md` | Step 9 — AI Summary |
+| `construction/functional-design.md` | Completion message — AI Summary |
+| `construction/nfr-requirements.md` | Completion message — AI Summary |
+| `construction/nfr-design.md` | Completion message — AI Summary |
+| `construction/code-generation.md` | Completion message — AI Summary |
+
+---
+
+## Acceptance Criteria for Fix
+
+- [ ] The word "optional" is removed from AI Summary descriptions in all affected rule files
+- [ ] The AI Summary is explicitly required, with flexible format
+- [ ] The AI Summary must include at minimum: artifacts created, key decisions, counts/metrics
+- [ ] The AI Summary must NOT include workflow navigation instructions (those belong in the WHAT'S NEXT block)
+- [ ] After the fix, completion messages consistently include a meaningful summary even when the model is context-constrained