4.6 KiB
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:
- Completion Announcement (mandatory)
- AI Summary — described as "optional" in the rule files
- 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
## 🔧 Units Generation Complete
> **📋 REVIEW REQUIRED:**
> ...
> **🚀 WHAT'S NEXT?**
> 🔧 Request Changes
> ✅ Approve & Continue
Expected Behavior
## 🔧 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):
**AI Summary** (optional): Provide structured bullet-point summary of...
Proposed fix:
**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