Skip to content

Commit 6d3fd87

Browse files
author
DavidQ
committed
PLAN_PR: bundle remaining sample polish work into minimal rule-safe waves
- reduces 7 remaining samples objectives into 3 future BUILD/APPLY waves - preserves one-purpose-per-PR rule - preserves testability and narrow scope - keeps canonical paths and Windows-safe execution intact Docs-only planning bundle
1 parent 4bb40c9 commit 6d3fd87

6 files changed

Lines changed: 189 additions & 13 deletions

File tree

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,40 @@
1+
# Codex command for PLAN_PR_SAMPLES_BUNDLED_FINALIZATION
2+
13
MODEL: GPT-5.4-codex
24
REASONING: high
35

46
COMMAND:
5-
Create PLAN_PR_SAMPLES_PREVIEW_ASSETS_AND_THUMBNAILS
7+
Create PLAN_PR_SAMPLES_BUNDLED_FINALIZATION as docs-only planning.
8+
9+
OBJECTIVE:
10+
Bundle the remaining samples PRs into the fewest rule-safe BUILD/APPLY waves.
11+
12+
CONSTRAINTS:
13+
- docs only
14+
- no implementation code
15+
- preserve one PR purpose only
16+
- preserve testability gate
17+
- preserve canonical sample paths
18+
- no gameplay scope
19+
- no engine-core scope
20+
- no start_of_day directory changes
21+
22+
PLANNING REQUIREMENTS:
23+
1. Cover all 7 remaining sample objectives
24+
2. Minimize the number of future BUILD/APPLY waves
25+
3. Do not combine incompatible purposes into one BUILD
26+
4. Keep each future BUILD testable
27+
5. Keep Windows-safe zero-dependency execution assumptions intact
628

7-
RULES:
8-
- Docs only
9-
- No implementation
29+
OUTPUT FILES:
30+
- docs/pr/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.md
31+
- docs/dev/codex_commands.md
32+
- docs/dev/commit_comment.txt
33+
- docs/dev/reports/change_summary.txt
34+
- docs/dev/reports/validation_checklist.txt
35+
- docs/dev/reports/file_tree_delta.txt
1036

11-
ZIP:
12-
<project folder>/tmp/PLAN_PR_SAMPLES_PREVIEW_ASSETS_AND_THUMBNAILS.zip
37+
ZIP OUTPUT REQUIREMENT:
38+
- MUST produce ZIP:
39+
<project folder>/tmp/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.zip
40+
- Task is not complete until the ZIP exists at that exact path

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
PLAN_PR: add preview assets and thumbnails to samples
1+
PLAN_PR: bundle remaining sample objectives into minimal safe BUILD/APPLY waves
2+
3+
- covers all 7 remaining sample objectives
4+
- minimizes future execution to 3 BUILD/APPLY waves
5+
- preserves one-purpose-per-PR rule and testability gate
6+
- preserves canonical sample paths and Windows-safe zero-dependency assumptions
7+
8+
Docs-only planning bundle

‎docs/dev/reports/change_summary.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
Define thumbnail + preview system for samples index and detail pages
1+
PR TYPE: PLAN
2+
PURPOSE: samples bundled finalization
3+
4+
SUMMARY:
5+
- defines the 7 remaining sample objectives to complete
6+
- bundles work into the minimum safe number of future BUILD/APPLY waves (3)
7+
- separates browse UX, discovery-data quality, and performance/personalization into compatible lanes
8+
- preserves one-purpose-per-PR, testability gates, canonical paths, and Windows-safe zero-dependency assumptions

‎docs/dev/reports/file_tree_delta.txt‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,12 @@
1-
ADDED: docs/pr/PLAN_PR_SAMPLES_PREVIEW_ASSETS_AND_THUMBNAILS.md
1+
PLAN OUTPUT ONLY
2+
3+
ADDED/UPDATED:
4+
- docs/pr/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.md
5+
- docs/dev/codex_commands.md
6+
- docs/dev/commit_comment.txt
7+
- docs/dev/reports/change_summary.txt
8+
- docs/dev/reports/validation_checklist.txt
9+
- docs/dev/reports/file_tree_delta.txt
10+
11+
NO IMPLEMENTATION FILES IN THIS PLAN
12+
NO GAMEPLAY OR ENGINE-CORE FILES CHANGED

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
[ ] thumbnail rules defined
2-
[ ] fallback defined
3-
[ ] no path changes
4-
[ ] zip exists
1+
[x] All 7 remaining sample objectives are covered
2+
[x] Bundling uses the fewest safe BUILD/APPLY waves
3+
[x] No future BUILD mixes incompatible PR purposes
4+
[x] Each future BUILD remains testable
5+
[x] Canonical path contract remains unchanged
6+
[x] Windows-safe zero-dependency assumptions remain intact
7+
[x] Output files generated at required docs paths
8+
[x] ZIP exists at <project folder>/tmp/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.zip

‎docs/pr/PLAN_PR_SAMPLES_BUNDLED_FINALIZATION.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# PLAN_PR_SAMPLES_BUNDLED_FINALIZATION
2+
3+
## Objective
4+
Bundle the remaining samples PRs into the fewest rule-safe BUILD/APPLY waves while preserving one-purpose-per-PR, testability, canonical paths, and Windows-safe zero-dependency execution.
5+
6+
## Scope
7+
Docs-only planning.
8+
No implementation code changes.
9+
No gameplay scope.
10+
No engine-core scope.
11+
No start_of_day directory changes.
12+
13+
## Remaining 7 Sample Objectives
14+
1. Preview assets and thumbnails
15+
2. Metadata validation hardening
16+
3. Index performance pass
17+
4. Tag standardization
18+
5. Navigation polish
19+
6. Hover preview
20+
7. Favorites/pinning
21+
22+
## Bundling Decision
23+
Minimum safe wave count: **3 BUILD/APPLY waves**.
24+
25+
Why not 1 wave:
26+
- mixes incompatible concerns and violates one-purpose intent.
27+
28+
Why not 2 waves:
29+
- still forces data-quality and performance/personalization concerns into the same BUILD.
30+
31+
Why 3 waves works:
32+
- each wave keeps a singular execution purpose,
33+
- each wave has a clear test surface,
34+
- each wave can fail fast cleanly.
35+
36+
## Wave Plan
37+
### Wave 1
38+
BUILD: `BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION`
39+
APPLY: `APPLY_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION`
40+
41+
Purpose:
42+
- browse-time UX enhancements.
43+
44+
Includes:
45+
- preview assets and thumbnails
46+
- hover preview
47+
- navigation polish
48+
49+
Testability gates:
50+
- index/detail render previews with deterministic fallback
51+
- next/previous/related navigation links resolve
52+
- representative links still load (first sample, last sample, 1316-1318)
53+
- no console errors on tested pages
54+
55+
### Wave 2
56+
BUILD: `BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY`
57+
APPLY: `APPLY_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY`
58+
59+
Purpose:
60+
- discovery data correctness.
61+
62+
Includes:
63+
- metadata validation hardening
64+
- tag standardization
65+
66+
Testability gates:
67+
- malformed metadata fails fast
68+
- duplicates/mismatch conditions fail fast
69+
- filter/search consistency improves with standardized tags
70+
- canonical paths unchanged
71+
72+
### Wave 3
73+
BUILD: `BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION`
74+
APPLY: `APPLY_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION`
75+
76+
Purpose:
77+
- index responsiveness and optional user personalization.
78+
79+
Includes:
80+
- index performance pass
81+
- favorites/pinning
82+
83+
Testability gates:
84+
- filter/search interactions remain responsive
85+
- favorites persist locally without external dependencies
86+
- no path contract changes
87+
- no gameplay or engine-core changes
88+
89+
## Compatibility Guardrails
90+
Do not combine in one BUILD:
91+
- discovery-data hardening with personalization features
92+
- performance optimizations with metadata schema policy changes
93+
- preview asset wiring with broad non-sample refactors
94+
95+
## Execution Order
96+
1. BUILD_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION
97+
2. APPLY_PR_SAMPLES_BROWSE_VISUALS_AND_NAVIGATION
98+
3. BUILD_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY
99+
4. APPLY_PR_SAMPLES_DISCOVERY_DATA_AND_FINDABILITY
100+
5. BUILD_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION
101+
6. APPLY_PR_SAMPLES_INDEX_PERFORMANCE_AND_PERSONALIZATION
102+
103+
## Windows-Safe Assumptions
104+
- zero dependency execution only
105+
- no npm install / no node_modules requirements
106+
- Node.js/vanilla JS-first scripts
107+
- deterministic local validation scripts
108+
109+
## Canonical Path Contract
110+
Must remain unchanged:
111+
- `samples/phaseXX/XXYY/index.html`
112+
113+
## Acceptance Criteria
114+
- all 7 remaining sample objectives are covered
115+
- bundling is minimized to the fewest safe waves
116+
- no incompatible purpose mixing per BUILD
117+
- each future BUILD remains testable
118+
- canonical path contract is preserved
119+
- Windows-safe zero-dependency assumptions are preserved

0 commit comments

Comments
 (0)