Adds profile and settings pages
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
# Gap Report: `classDiagram` Coloring Reliably Breaks `domain-entities.md`
|
||||
|
||||
**Gap ID**: gap-003
|
||||
**Reported**: 2026-06-22
|
||||
**Reporter**: User (via cms-frontend Unit 6 Functional Design session)
|
||||
**Skill affected**: `aidlc-workflow`
|
||||
**Rule files affected**:
|
||||
- `.aidlc-rule-details/construction/functional-design.md` — Step 7, "Diagram types per artifact"
|
||||
- `.aidlc-rule-details/common/mermaid-diagram-standards.md` — missing validated `classDiagram` example
|
||||
|
||||
---
|
||||
|
||||
## Problem Description
|
||||
|
||||
Every time `domain-entities.md` is generated by the Functional Design stage, the entity diagram is broken on the first attempt. It requires manual correction from the user before it renders.
|
||||
|
||||
This happened in both the `slp-modular-cms-api` and `cms-frontend` features. It is a **structural, repeatable failure** caused by a conflict between the diagram type prescribed by the rules and the actual Mermaid behavior.
|
||||
|
||||
---
|
||||
|
||||
## Root Cause
|
||||
|
||||
### Prescribed rule (functional-design.md, Step 7)
|
||||
|
||||
```
|
||||
domain-entities.md → `classDiagram` for entity relationships
|
||||
(supports `classDef` coloring), NOT `erDiagram`
|
||||
```
|
||||
|
||||
The claim "(supports `classDef` coloring)" is misleading. There are **two failure modes** that make colored `classDiagram` unreliable in practice:
|
||||
|
||||
### Failure Mode 1: `class ClassName style` conflicts with body-defined classes
|
||||
|
||||
When a class is defined with a body block:
|
||||
```
|
||||
class AuthUser {
|
||||
+string id
|
||||
+string email
|
||||
}
|
||||
```
|
||||
|
||||
...and then a `classDef` style is applied using the flowchart-style pattern:
|
||||
```
|
||||
classDef user fill:#2196F3,color:#000
|
||||
class AuthUser user
|
||||
```
|
||||
|
||||
Mermaid interprets `class AuthUser user` as a **second class declaration** that conflicts with the already-defined body. The diagram breaks. This is the #1 failure pattern because the AI model uses the flowchart `classDef`/`class` pattern (which is well-documented in `mermaid-diagram-standards.md`) and applies it to `classDiagram` — where it doesn't work the same way.
|
||||
|
||||
### Failure Mode 2: `:::` inline notation is unreliable
|
||||
|
||||
The alternative syntax — applying a `classDef` inline in the class header:
|
||||
```
|
||||
class AuthUser:::user {
|
||||
+string id
|
||||
}
|
||||
```
|
||||
|
||||
...is **not reliably supported across Mermaid versions** and also broke on this user's renderer.
|
||||
|
||||
### Contributing factor: No validated `classDiagram` example in standards
|
||||
|
||||
`mermaid-diagram-standards.md` provides validated, working examples for:
|
||||
- `graph LR/TD` (flowchart) ✅
|
||||
- `sequenceDiagram` ✅
|
||||
|
||||
It **does not** provide any validated working example for `classDiagram` with `classDef` coloring. So the AI model has no reliable template to follow and defaults to flowchart patterns — which break in `classDiagram`.
|
||||
|
||||
---
|
||||
|
||||
## Observed Symptom Pattern
|
||||
|
||||
1. AI generates `domain-entities.md` with `classDiagram` + `classDef` coloring
|
||||
2. Diagram is broken (either body-block conflict or `:::` not supported)
|
||||
3. User reports broken diagram
|
||||
4. AI attempts fix with `:::` notation → still broken
|
||||
5. AI converts to `graph TD` → diagram works
|
||||
6. **Total: 2 failed attempts before success, requiring user intervention**
|
||||
|
||||
This pattern occurred identically in Unit 6 of the `cms-frontend` feature (2026-06-22).
|
||||
|
||||
---
|
||||
|
||||
## Proven Fix (from this session)
|
||||
|
||||
Converting `domain-entities.md` to use `graph TD` instead of `classDiagram` works reliably:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
AuthUser["AuthUser"]
|
||||
UpdateProfileRequest["UpdateProfileRequest"]
|
||||
|
||||
AuthUser -->|"provides data for"| UpdateProfileRequest
|
||||
|
||||
classDef user fill:#2196F3,stroke:#0d47a1,color:#000
|
||||
classDef request fill:#FF9800,stroke:#e65100,color:#000
|
||||
|
||||
class AuthUser user
|
||||
class UpdateProfileRequest request
|
||||
```
|
||||
|
||||
`graph TD` with `classDef`/`class` is:
|
||||
- Well-documented with a validated example in `mermaid-diagram-standards.md`
|
||||
- Consistently supported across Mermaid versions
|
||||
- Sufficient to express entity relationships (via labeled directed edges)
|
||||
|
||||
The entity field details (types, required/optional, descriptions) are better placed in the **tables below the diagram** than in the class body nodes anyway — keeping the diagram clean and the data queryable.
|
||||
|
||||
---
|
||||
|
||||
## Suggested Fix
|
||||
|
||||
### Fix 1 (Primary — required): Update `functional-design.md`
|
||||
|
||||
In Step 7, "Diagram types per artifact", change:
|
||||
|
||||
**Current**:
|
||||
```
|
||||
domain-entities.md → `classDiagram` for entity relationships
|
||||
(supports `classDef` coloring), NOT `erDiagram`
|
||||
```
|
||||
|
||||
**Replace with**:
|
||||
```
|
||||
domain-entities.md → `graph TD` for entity relationships.
|
||||
- Use labeled edges (|"relationship label"|) to show how entities connect
|
||||
- Use `classDef`/`class` for coloring (same pattern as flowcharts)
|
||||
- Do NOT use `classDiagram` — classDef coloring is unreliable in classDiagram
|
||||
- Do NOT use `erDiagram` — no color support
|
||||
- Keep entity field details in Markdown tables below the diagram, not in diagram nodes
|
||||
```
|
||||
|
||||
### Fix 2 (Secondary — recommended): Update `mermaid-diagram-standards.md`
|
||||
|
||||
Add an explicit warning and a `graph TD` entity diagram example to `mermaid-diagram-standards.md`:
|
||||
|
||||
```markdown
|
||||
## Entity Relationship Diagrams
|
||||
|
||||
Use `graph TD` for entity diagrams — NOT `classDiagram` (classDef coloring is
|
||||
unreliable in classDiagram) and NOT `erDiagram` (no color support).
|
||||
|
||||
Example:
|
||||
graph TD
|
||||
User["User"]
|
||||
Order["Order"]
|
||||
Product["Product"]
|
||||
|
||||
User -->|"places"| Order
|
||||
Order -->|"contains"| Product
|
||||
|
||||
classDef entity fill:#2196F3,stroke:#0d47a1,color:#000
|
||||
classDef value fill:#FF9800,stroke:#e65100,color:#000
|
||||
|
||||
class User,Order entity
|
||||
class Product value
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria for Fix
|
||||
|
||||
- [ ] `functional-design.md` Step 7 prescribes `graph TD` for `domain-entities.md`, not `classDiagram`
|
||||
- [ ] The reason for avoiding `classDiagram` is documented in the rule (prevents future regression)
|
||||
- [ ] `mermaid-diagram-standards.md` includes a validated `graph TD` entity diagram example
|
||||
- [ ] A note in `mermaid-diagram-standards.md` explicitly warns against `classDiagram` for colored entity diagrams
|
||||
- [ ] After the fix, generating `domain-entities.md` produces a working diagram on the first attempt without user correction
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- Skill: `C:\Users\Bryan\.claude\skills\aidlc-workflow\`
|
||||
- Primary rule: `.aidlc-rule-details/construction/functional-design.md` — Step 7
|
||||
- Supporting rule: `.aidlc-rule-details/common/mermaid-diagram-standards.md`
|
||||
- Example broken file: `K:\Development\Projects\SlpModularCms\aidlc-docs\features\cms-frontend\construction\unit-6\functional-design\domain-entities.md` (fixed in session, now uses `graph TD`)
|
||||
|
||||
---
|
||||
|
||||
## Workaround (for current sessions)
|
||||
|
||||
When generating `domain-entities.md`, use `graph TD` instead of `classDiagram`. Apply the standard `classDef`/`class` pattern. Place entity field details in Markdown tables below the diagram rather than in diagram node bodies.
|
||||
@@ -0,0 +1,133 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user