Skip to content

Commit 1006fae

Browse files
DestinyOfLoveDestinyOfLove
committed
fix: address review findings for plan doc rendering and Memory Doctor
- Fix Diagnosis.to_dict() to include full decision_a/decision_b dicts, preventing silent failures in run_apply() (Issue 3.2) - Add explicit --apply instructions to passive conflict check in hybrid-auto.md and mega-plan.md (Issue 3.1) - Reorder ADR confirmation before unified review display so review reflects any decision modifications (Issue 3.5) - Add prd.md, design_doc.md, mega-plan.md to .gitignore and PLAN_CASCADE_GITIGNORE_ENTRIES (Issue 3.3) - Add comment explaining design_doc.json always in project root (3.8) - Add 86 tests for render-plan-docs.py covering all renderers, edge cases, and batch calculation (Issue 3.9)
1 parent 4a5a5e7 commit 1006fae

File tree

7 files changed

+1290
-80
lines changed

7 files changed

+1290
-80
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,11 @@ htmlcov/
7676

7777
# Planning documents
7878
prd.json
79+
prd.md
7980
mega-plan.json
81+
mega-plan.md
8082
design_doc.json
83+
design_doc.md
8184

8285
# Status and state files
8386
.mega-status.json

‎commands/hybrid-auto.md‎

Lines changed: 73 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -697,7 +697,48 @@ If exit code is 1:
697697
- **Deprecate** — Mark the older/conflicting decision as deprecated (recommended for conflicts and superseded)
698698
- **Merge** — Combine duplicate decisions into one (recommended for duplicates)
699699
- **Skip** — Keep both decisions as-is
700-
3. Apply the user's choices by modifying the relevant `design_doc.json` files
700+
3. Apply the user's choices using the memory-doctor `--apply` command:
701+
702+
**CRITICAL**: Construct a JSON array of the user's choices and save it to `_doctor_actions.json`. Each entry must include the full diagnosis context with `decision_a` and `decision_b` dicts (including `id` and `_source` fields) as returned by the diagnosis report:
703+
704+
```json
705+
[
706+
{
707+
"action": "deprecate",
708+
"diagnosis": {
709+
"type": "conflict",
710+
"decision_a": {"id": "ADR-F003", "_source": "path/to/design_doc.json"},
711+
"decision_b": {"id": "ADR-F012", "_source": "other/design_doc.json"},
712+
"source_a": "path/to/design_doc.json",
713+
"source_b": "other/design_doc.json"
714+
}
715+
},
716+
{
717+
"action": "merge",
718+
"diagnosis": {
719+
"type": "duplicate",
720+
"decision_a": {"id": "ADR-F005", "_source": "path/to/design_doc.json"},
721+
"decision_b": {"id": "ADR-F009", "_source": "other/design_doc.json"},
722+
"source_a": "path/to/design_doc.json",
723+
"source_b": "other/design_doc.json"
724+
}
725+
}
726+
]
727+
```
728+
729+
Then run the apply command:
730+
```bash
731+
uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/memory-doctor.py" \
732+
--apply _doctor_actions.json \
733+
--project-root "$(pwd)"
734+
```
735+
736+
Clean up the temporary file:
737+
```bash
738+
rm -f _doctor_actions.json
739+
```
740+
741+
Note: Entries where the user chose **Skip** should be omitted from the actions array entirely.
701742

702743
## Step 5.45: Generate Markdown Documents
703744

@@ -716,34 +757,11 @@ This produces:
716757
These files are programmatically generated from JSON (not LLM) and stay in sync.
717758
If the script fails, log a warning and continue — the Markdown files are supplementary.
718759

719-
## Step 5.5: Display Unified Review
760+
## Step 5.5: Confirm Architectural Decisions
720761

721-
**CRITICAL**: Use Bash to display the unified PRD + Design Document review:
762+
Before the unified review, display a decision summary and confirm with the user. This ensures any modifications during confirmation are reflected in the unified review displayed afterward.
722763

723-
```bash
724-
uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/unified-review.py" --mode hybrid
725-
```
726-
727-
This displays:
728-
- PRD summary with stories, priorities, and execution batches
729-
- Design document with components, patterns, and architectural decisions
730-
- Story-to-design mappings (showing which stories are linked to which components)
731-
- Warnings for any unmapped stories
732-
- Flow/TDD configuration summary (if set)
733-
- Available next steps
734-
735-
If the script is not available, display a manual summary showing:
736-
- Goal and objectives
737-
- All stories with IDs, titles, priorities
738-
- Design document summary (components, patterns, decisions)
739-
- Flow configuration: {FLOW_LEVEL or "standard (default)"}
740-
- TDD mode: {TDD_MODE or "auto (default)"}
741-
742-
## Step 5.6: Confirm Architectural Decisions
743-
744-
After the unified review, display a decision summary and confirm with the user.
745-
746-
### 5.6.1: Display Decision Summary
764+
### 5.5.1: Display Decision Summary
747765

748766
Read `design_doc.json` and for each decision with status "accepted" or "proposed", display:
749767

@@ -764,13 +782,13 @@ Total: N decisions
764782
============================================================
765783
```
766784

767-
### 5.6.2: Confirmation Flow
785+
### 5.5.2: Confirmation Flow
768786

769787
**If `NO_CONFIRM_MODE` is true** (i.e., `--no-confirm` was passed):
770788
- Skip interactive confirmation entirely
771789
- Auto-accept all decisions: set every decision's status to "accepted" in `design_doc.json`
772790
- Log: `"Auto-accepted N architectural decisions (--no-confirm mode)"`
773-
- Proceed to Step 6
791+
- Proceed to Step 5.6
774792

775793
**Otherwise** (interactive mode — the default):
776794

@@ -785,9 +803,9 @@ Options:
785803
3. "Discuss" — Chat about specific decisions before confirming
786804
```
787805

788-
**If user selects "Accept All"**: Set all decision statuses to "accepted" in `design_doc.json`. Proceed to Step 6.
806+
**If user selects "Accept All"**: Set all decision statuses to "accepted" in `design_doc.json`. Proceed to Step 5.6.
789807

790-
**If user selects "Discuss"**: Let the user discuss freely. After the discussion, repeat Step 5.6.2 (re-ask the question).
808+
**If user selects "Discuss"**: Let the user discuss freely. After the discussion, repeat Step 5.5.2 (re-ask the question).
791809

792810
**If user selects "Review Individually"**: For each decision, use `AskUserQuestion`:
793811

@@ -816,9 +834,32 @@ uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/render-plan-doc
816834
--project-root "$(pwd)"
817835
```
818836

837+
## Step 5.6: Display Unified Review
838+
839+
**CRITICAL**: Use Bash to display the unified PRD + Design Document review. This is displayed after ADR confirmation so it reflects any decision modifications made during Step 5.5:
840+
841+
```bash
842+
uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/unified-review.py" --mode hybrid
843+
```
844+
845+
This displays:
846+
- PRD summary with stories, priorities, and execution batches
847+
- Design document with components, patterns, and architectural decisions
848+
- Story-to-design mappings (showing which stories are linked to which components)
849+
- Warnings for any unmapped stories
850+
- Flow/TDD configuration summary (if set)
851+
- Available next steps
852+
853+
If the script is not available, display a manual summary showing:
854+
- Goal and objectives
855+
- All stories with IDs, titles, priorities
856+
- Design document summary (components, patterns, decisions)
857+
- Flow configuration: {FLOW_LEVEL or "standard (default)"}
858+
- TDD mode: {TDD_MODE or "auto (default)"}
859+
819860
## Step 6: Confirm Generation Complete and Show Next Steps
820861

821-
After displaying the unified review and getting decision confirmation, show how to proceed:
862+
After displaying the unified review, show how to proceed:
822863

823864
```
824865
PRD and Design Document generated successfully!

‎commands/mega-plan.md‎

Lines changed: 89 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -546,7 +546,48 @@ If exit code is 1:
546546
- **Deprecate** — Mark the older/conflicting decision as deprecated (recommended for conflicts and superseded)
547547
- **Merge** — Combine duplicate decisions into one (recommended for duplicates)
548548
- **Skip** — Keep both decisions as-is
549-
3. Apply the user's choices by modifying the relevant `design_doc.json` files
549+
3. Apply the user's choices using the memory-doctor `--apply` command:
550+
551+
**CRITICAL**: Construct a JSON array of the user's choices and save it to `_doctor_actions.json`. Each entry must include the full diagnosis context with `decision_a` and `decision_b` dicts (including `id` and `_source` fields) as returned by the diagnosis report:
552+
553+
```json
554+
[
555+
{
556+
"action": "deprecate",
557+
"diagnosis": {
558+
"type": "conflict",
559+
"decision_a": {"id": "ADR-003", "_source": "path/to/design_doc.json"},
560+
"decision_b": {"id": "ADR-012", "_source": "other/design_doc.json"},
561+
"source_a": "path/to/design_doc.json",
562+
"source_b": "other/design_doc.json"
563+
}
564+
},
565+
{
566+
"action": "merge",
567+
"diagnosis": {
568+
"type": "duplicate",
569+
"decision_a": {"id": "ADR-005", "_source": "path/to/design_doc.json"},
570+
"decision_b": {"id": "ADR-009", "_source": "other/design_doc.json"},
571+
"source_a": "path/to/design_doc.json",
572+
"source_b": "other/design_doc.json"
573+
}
574+
}
575+
]
576+
```
577+
578+
Then run the apply command:
579+
```bash
580+
uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/memory-doctor.py" \
581+
--apply _doctor_actions.json \
582+
--project-root "$(pwd)"
583+
```
584+
585+
Clean up the temporary file:
586+
```bash
587+
rm -f _doctor_actions.json
588+
```
589+
590+
Note: Entries where the user chose **Skip** should be omitted from the actions array entirely.
550591

551592
### 5.4: Generate Markdown Documents
552593

@@ -638,50 +679,11 @@ Options:
638679

639680
Update `mega-plan.json` with the chosen mode.
640681

641-
## Step 9: Display Unified Review
682+
## Step 9: Confirm Architectural Decisions
642683

643-
**CRITICAL**: Use Bash to display the unified Mega-Plan + Design Document review:
684+
Before the unified review, display a decision summary and confirm with the user. This ensures any modifications during confirmation are reflected in the unified review displayed afterward.
644685

645-
```bash
646-
uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/unified-review.py" --mode mega
647-
```
648-
649-
This displays:
650-
- Mega-plan summary with features, priorities, and execution batches
651-
- Project-level design document with system architecture, components, and patterns
652-
- Feature-to-design mappings (showing which features use which components)
653-
- Warnings for any unmapped features
654-
- Available next steps
655-
656-
If the script is not available, display a manual summary:
657-
658-
```
659-
============================================================
660-
MEGA PLAN CREATED
661-
============================================================
662-
663-
Goal: <goal>
664-
Execution Mode: <auto|manual>
665-
Target Branch: <target_branch>
666-
Total Features: <count>
667-
668-
Feature Batches:
669-
670-
Batch 1 (Parallel - No Dependencies):
671-
- feature-001: <title> [high]
672-
- feature-002: <title> [high]
673-
674-
Batch 2 (After Batch 1):
675-
- feature-003: <title> [medium] (depends on: feature-001, feature-002)
676-
677-
============================================================
678-
```
679-
680-
## Step 9.5: Confirm Architectural Decisions
681-
682-
After the unified review, display a decision summary and confirm with the user.
683-
684-
### 9.5.1: Display Decision Summary
686+
### 9.1: Display Decision Summary
685687

686688
Read `design_doc.json` and for each decision with status "accepted" or "proposed", display:
687689

@@ -702,13 +704,13 @@ Total: N decisions
702704
============================================================
703705
```
704706

705-
### 9.5.2: Confirmation Flow
707+
### 9.2: Confirmation Flow
706708

707709
**If `NO_CONFIRM_MODE` is true** (i.e., `--no-confirm` was passed):
708710
- Skip interactive confirmation entirely
709711
- Auto-accept all decisions: set every decision's status to "accepted" in `design_doc.json`
710712
- Log: `"Auto-accepted N architectural decisions (--no-confirm mode)"`
711-
- Proceed to Step 10
713+
- Proceed to Step 9.5
712714

713715
**Otherwise** (interactive mode — the default):
714716

@@ -723,9 +725,9 @@ Options:
723725
3. "Discuss" — Chat about specific decisions before confirming
724726
```
725727

726-
**If user selects "Accept All"**: Set all decision statuses to "accepted" in `design_doc.json`. Proceed to Step 10.
728+
**If user selects "Accept All"**: Set all decision statuses to "accepted" in `design_doc.json`. Proceed to Step 9.5.
727729

728-
**If user selects "Discuss"**: Let the user discuss freely. After the discussion, repeat Step 9.5.2 (re-ask the question).
730+
**If user selects "Discuss"**: Let the user discuss freely. After the discussion, repeat Step 9.2 (re-ask the question).
729731

730732
**If user selects "Review Individually"**: For each decision, use `AskUserQuestion`:
731733

@@ -754,9 +756,48 @@ uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/render-plan-doc
754756
--project-root "$(pwd)"
755757
```
756758

759+
## Step 9.5: Display Unified Review
760+
761+
**CRITICAL**: Use Bash to display the unified Mega-Plan + Design Document review. This is displayed after ADR confirmation so it reflects any decision modifications made during Step 9:
762+
763+
```bash
764+
uv run python "${CLAUDE_PLUGIN_ROOT}/skills/hybrid-ralph/scripts/unified-review.py" --mode mega
765+
```
766+
767+
This displays:
768+
- Mega-plan summary with features, priorities, and execution batches
769+
- Project-level design document with system architecture, components, and patterns
770+
- Feature-to-design mappings (showing which features use which components)
771+
- Warnings for any unmapped features
772+
- Available next steps
773+
774+
If the script is not available, display a manual summary:
775+
776+
```
777+
============================================================
778+
MEGA PLAN CREATED
779+
============================================================
780+
781+
Goal: <goal>
782+
Execution Mode: <auto|manual>
783+
Target Branch: <target_branch>
784+
Total Features: <count>
785+
786+
Feature Batches:
787+
788+
Batch 1 (Parallel - No Dependencies):
789+
- feature-001: <title> [high]
790+
- feature-002: <title> [high]
791+
792+
Batch 2 (After Batch 1):
793+
- feature-003: <title> [medium] (depends on: feature-001, feature-002)
794+
795+
============================================================
796+
```
797+
757798
## Step 10: Show Files Created and Next Steps
758799

759-
After unified review and getting decision confirmation, show created files and execution configuration:
800+
After displaying the unified review, show created files and execution configuration:
760801

761802
```
762803
Files created:

‎skills/hybrid-ralph/scripts/render-plan-docs.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -459,6 +459,10 @@ def main():
459459
output_files.append(str(out_path))
460460

461461
# Load and render design_doc.json (both modes)
462+
# NOTE: design_doc.json is always in project root (not via PathResolver) because
463+
# it is a user-visible file that lives alongside the source code, unlike prd.json
464+
# and mega-plan.json which may be stored in platform-specific directories.
465+
# See also: unified-review.py load_documents() which follows the same convention.
462466
design_doc = load_json_file(project_root / "design_doc.json")
463467
if design_doc:
464468
design_md = render_design_doc_md(design_doc)

‎src/plan_cascade/core/memory_doctor.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ def to_dict(self) -> dict:
4646
"type": self.type.value,
4747
"decision_a_id": self.decision_a.get("id", "unknown"),
4848
"decision_b_id": self.decision_b.get("id", "unknown"),
49+
"decision_a": self.decision_a,
50+
"decision_b": self.decision_b,
4951
"explanation": self.explanation,
5052
"suggestion": self.suggestion,
5153
"source_a": self.source_a,

‎src/plan_cascade/utils/gitignore.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,11 @@
2626
"spec.json",
2727
"spec.md",
2828
"prd.json",
29+
"prd.md",
2930
"mega-plan.json",
31+
"mega-plan.md",
3032
"design_doc.json",
33+
"design_doc.md",
3134
"",
3235
"# Status and state files",
3336
".mega-status.json",

0 commit comments

Comments
 (0)