# 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