134 lines
7.7 KiB
Markdown
134 lines
7.7 KiB
Markdown
# Gap Report: active-features.md Not Updated as Feature Progresses or Completes
|
|
|
|
**Gap ID**: gap-005
|
|
**Reported**: 2026-06-22
|
|
**Reporter**: User (via cms-frontend workflow session)
|
|
**Skill affected**: `aidlc-workflow`
|
|
**Rule files affected**:
|
|
- `.aidlc-rule-details/inception/workspace-detection.md` — Step 4d (initial registration)
|
|
- `SKILL.md` — Operations section / Key Principles / Workflow Complete block
|
|
- `.aidlc-rule-details/construction/build-and-test.md` — Step 8 (Update State Tracking)
|
|
- `.aidlc-rule-details/operations/operations.md` — Workflow Complete block
|
|
|
|
---
|
|
|
|
## Observed Behavior
|
|
|
|
`aidlc-docs/active-features.md` is written exactly once — at feature creation (Step 4d of `workspace-detection.md`) — and is **never updated thereafter**. The feature's status row remains frozen at `🔵 Inception` regardless of how far the workflow has advanced.
|
|
|
|
For `cms-frontend`, all 6 construction units are complete and Build and Test is ready to start, yet `active-features.md` still shows:
|
|
|
|
```
|
|
| CMS Frontend (cms-frontend) | 🔵 Inception | unknown | Frontend, Identity (Auth), Availability | 2026-06-16 |
|
|
```
|
|
|
|
The status emoji guide defined in Step 4d of `workspace-detection.md` describes four states (`🔵 Inception · 🟢 Construction · 🟡 Operations · ✅ Complete`) but **no rule in the skill instructs the model to use any state beyond `🔵 Inception`**.
|
|
|
|
---
|
|
|
|
## Expected Behavior
|
|
|
|
`active-features.md` should be kept in sync with the feature's actual phase throughout the workflow. Specifically:
|
|
|
|
| Trigger | New status in active-features.md |
|
|
|---|---|
|
|
| Inception phase complete / first Construction stage begins | `🟢 Construction` |
|
|
| Build and Test approved / Operations phase entered | `🟡 Operations` (or `✅ Complete` if Operations is skipped) |
|
|
| Workflow complete (Operations placeholder acknowledged) | `✅ Complete` |
|
|
|
|
When the feature has no Operations phase (as with `cms-frontend`, where the Operations stage is a placeholder), the status should transition directly from `🟢 Construction` to `✅ Complete` upon Build and Test approval.
|
|
|
|
The `active-features.md` index is the primary multi-feature dashboard. It is read during session resumption (`session-continuity.md`) and displayed to the user in the Welcome Back prompt. Stale status data directly degrades the session-resume experience.
|
|
|
|
---
|
|
|
|
## Root Cause
|
|
|
|
The gap has two dimensions:
|
|
|
|
**1. Missing transition instructions (phase change)**
|
|
No rule file specifies that `active-features.md` must be updated when the workflow transitions from one phase to another. The status emoji guide exists in `workspace-detection.md` Step 4d as documentation, but no subsequent stage instructs the model to write those updated rows.
|
|
|
|
**2. Missing completion instruction**
|
|
`SKILL.md` (Operations section, "Workflow Complete" block) and `operations/operations.md` both declare that the workflow ends after Build and Test approval, and that the model should present a closing summary. Neither file includes an instruction to update `active-features.md` to `✅ Complete`. Similarly, `construction/build-and-test.md` Step 8 ("Update State Tracking") only mentions updating `aidlc-state.md`, not `active-features.md`.
|
|
|
|
In short: `active-features.md` is treated as a write-once registration file rather than a living index.
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
- Session resume (Welcome Back prompt from `session-continuity.md`) shows incorrect phase for all features
|
|
- Users cannot determine which features are genuinely in progress vs. complete by looking at `active-features.md`
|
|
- Conflict detection (Step 5 of `workspace-detection.md`) may incorrectly flag a completed feature as still active, because it keys on `status not ✅ Complete`
|
|
- The multi-feature dashboard is unreliable; the user must manually inspect each feature's `aidlc-state.md` to learn the real status
|
|
|
|
---
|
|
|
|
## Proposed Fix
|
|
|
|
Add explicit `active-features.md` update instructions at the two natural transition points and at workflow completion:
|
|
|
|
### Fix 1 — Phase transition: Inception → Construction
|
|
|
|
In `construction/code-generation.md` (or wherever the first construction stage begins), add to the "Update State Tracking" step:
|
|
|
|
> **Also update `aidlc-docs/active-features.md`**: Change the feature's status column from `🔵 Inception` to `🟢 Construction`.
|
|
|
|
### Fix 2 — Workflow completion: Build and Test approved
|
|
|
|
In `construction/build-and-test.md` Step 8 ("Update State Tracking"), extend the existing instruction:
|
|
|
|
> **Also update `aidlc-docs/active-features.md`**: If the feature has no active Operations phase (Operations is a placeholder), change the feature's status to `✅ Complete`. If an Operations phase will follow, change status to `🟡 Operations`.
|
|
|
|
Replicate the same instruction in the "Workflow Complete" block in `SKILL.md` (Operations section) and in `operations/operations.md`.
|
|
|
|
### Fix 3 — Clarify the status emoji guide is actionable
|
|
|
|
In `workspace-detection.md` Step 4d, add a note below the status emoji guide making clear that status updates are mandatory as the workflow progresses:
|
|
|
|
> **Note**: Status values are not static. The model MUST update the feature's row in `active-features.md` whenever the workflow transitions between phases, and again when the workflow completes.
|
|
|
|
### Fix 4 — Session continuity awareness
|
|
|
|
In `session-continuity.md`, under "MANDATORY: Session Continuity Instructions", add a consistency check:
|
|
|
|
> When resuming a feature, compare the phase shown in `active-features.md` against `aidlc-state.md`. If they diverge, correct `active-features.md` to match `aidlc-state.md` before presenting the Welcome Back prompt.
|
|
|
|
---
|
|
|
|
## Skill Files to Update
|
|
|
|
| File | Change |
|
|
|---|---|
|
|
| `C:\Users\Bryan\.claude\skills\aidlc-workflow\.aidlc-rule-details\construction\build-and-test.md` | Step 8: add `active-features.md` update to `✅ Complete` (or `🟡 Operations`) |
|
|
| `C:\Users\Bryan\.claude\skills\aidlc-workflow\.aidlc-rule-details\construction\code-generation.md` | State tracking step: add `active-features.md` update to `🟢 Construction` on first construction unit |
|
|
| `C:\Users\Bryan\.claude\skills\aidlc-workflow\SKILL.md` | Operations "Workflow Complete" block: add `active-features.md` update to `✅ Complete` |
|
|
| `C:\Users\Bryan\.claude\skills\aidlc-workflow\.aidlc-rule-details\operations\operations.md` | Add "Workflow Complete" instructions including `active-features.md` update |
|
|
| `C:\Users\Bryan\.claude\skills\aidlc-workflow\.aidlc-rule-details\inception\workspace-detection.md` | Step 4d: add note that status must be updated as workflow progresses |
|
|
| `C:\Users\Bryan\.claude\skills\aidlc-workflow\.aidlc-rule-details\common\session-continuity.md` | Add consistency check: correct `active-features.md` on resume if it diverges from `aidlc-state.md` |
|
|
|
|
---
|
|
|
|
## Workaround (for current session)
|
|
|
|
For `cms-frontend` in `K:\Development\Projects\SlpModularCms`: manually update `aidlc-docs/active-features.md` — change status from `🔵 Inception` to `✅ Complete`, because all 6 units are done, Build and Test is the only remaining step, and there is no active Operations phase for this feature.
|
|
|
|
This gap report was filed as part of applying that manual correction.
|
|
|
|
---
|
|
|
|
## Acceptance Criteria for Fix
|
|
|
|
- [ ] Starting a new Construction stage updates `active-features.md` status to `🟢 Construction`
|
|
- [ ] Build and Test approval updates `active-features.md` status to `✅ Complete` (no Operations) or `🟡 Operations` (active Operations)
|
|
- [ ] Session resume detects and corrects stale `active-features.md` status automatically
|
|
- [ ] Step 4d in `workspace-detection.md` explicitly notes the status is not write-once
|
|
- [ ] All six skill files listed above are updated consistently
|
|
|
|
---
|
|
|
|
**Opened**: 2026-06-22
|
|
**Status**: Open
|
|
**Severity**: Medium (dashboard unreliable; session-resume quality degraded; conflict detection may produce false positives)
|