7.7 KiB
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 onstatus not ✅ Complete - The multi-feature dashboard is unreliable; the user must manually inspect each feature's
aidlc-state.mdto 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🔵 Inceptionto🟢 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.mdwhenever 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.mdagainstaidlc-state.md. If they diverge, correctactive-features.mdto matchaidlc-state.mdbefore 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.mdstatus to🟢 Construction - Build and Test approval updates
active-features.mdstatus to✅ Complete(no Operations) or🟡 Operations(active Operations) - Session resume detects and corrects stale
active-features.mdstatus automatically - Step 4d in
workspace-detection.mdexplicitly 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)