122 lines
4.6 KiB
Markdown
122 lines
4.6 KiB
Markdown
# 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
|