experiment: review deferred project documents
Experiment 30 classified two deferred documents against verified current state: - architectural-principles.md → keep as task-specific reference (6 current, 4 aspirational, 3 duplicates) - backlog info.md → retain temporarily pending revision (mixed mock fixtures + deferred UX planning) Neither moved to archive — both contain material with potential near-term utility. Created docs/document-role-review.md with evidence, routing test, and return-to-work note.
This commit is contained in:
@@ -1758,3 +1758,50 @@ These are observations, not implementation tasks.
|
||||
- Narrative testing
|
||||
- Narrative localisation
|
||||
- Multiple narrative projections
|
||||
|
||||
## Experiment 30 — Review Deferred Project Documents
|
||||
|
||||
**Status:** Pending Rob's review
|
||||
|
||||
### Hypothesis
|
||||
|
||||
Each deferred document can be classified by comparing it with the verified current project state without reopening the full experiment history or rewriting its contents. The result may be: keep as current guidance, keep as task-specific reference, archive as historical evidence, or retain temporarily pending revision. No additional categories should be invented.
|
||||
|
||||
### Review of architectural-principles.md
|
||||
|
||||
- **14 principles assessed against verified implementation:**
|
||||
- **6 current (match runtime or guardrails):** P1 (layer separation), P3 (user feedback loop), P4 (reasoning/UI separation), P6 (presentation renders, does not interpret), P8 (narrative never invents facts), P14 (user as first-class input).
|
||||
- **4 aspirational targets:** P5 (behaviour never reasons — module exists with zero callers), P10 (convergence over single signals — no mechanism), P11 (stateful assessment across turns — partially present), P12 (assessable uncertainty — absent).
|
||||
- **4 mixed/unclear:** P2 (information flows downward — partially matches but passive layers don't fit the cascade model), P7 (assessment never generates evidence — diagnostic_only but scope-aware condition status makes interpretive judgments), P9 (assessment describes not prescribes — signals descriptive, but decision-condition evaluation borders on prescription), P13 (progress qualitative not quantitative — product direction supports; unknown selection uses node status qualitatively but not verified).
|
||||
- **3 duplicated with guardrails:** P1 overlaps with architecture-guardrails' prohibition list. P4 overlaps with UX-task boundaries in guardrails. P8 overlaps with the explicit invariant "every question comes from a resolved graph node." Overlap adds value: guardrails state boundaries; principles explain why.
|
||||
|
||||
- **Role assigned:** Keep as task-specific reference. Six current principles and four aspirational targets make it valuable when resuming reasoning architecture work. Three duplications reduce (but don't eliminate) its independent value — the derived-from/implication context adds what guardrails lack. project-knowledge-inventory already listed it under "Review Before Archive"; confirmed as task-specific reference.
|
||||
|
||||
### Review of backlog info.md
|
||||
|
||||
- **Content analysis:**
|
||||
- **Still-relevant (≈20 lines):** Mock fixtures table — 15 scenario types with purposes and examples. Directly useful when UI work resumes.
|
||||
- **Historical/aspirational (≈370 lines):** UX roadmap phases 1–4 with wireframe text, animation specs, loading messages. Design intent is valid; specifics may change when UI resumes. Untracked — no commit/PR linkage.
|
||||
- **Duplicates:** Phase 4 "Mock Scenario Library" duplicates the fixtures table at top. "Deliberately Out of Scope" repeats pause decision in current-project-state and project-context.
|
||||
|
||||
- **Role assigned:** Retain temporarily pending revision. The mock fixtures table is too useful to lose in an archive, but the document's mixed role (useful reference + deferred planning) needs resolution when UI work resumes. Splitting the file or archiving portions requires revising content — constraints forbid this now.
|
||||
|
||||
### Practical Routing Test Result
|
||||
|
||||
**Task:** A future Claude session is about to work on UI mocks. Should it read architectural-principles.md, backlog info.md, both, or neither?
|
||||
|
||||
**Answer: Both.** Backlog info.md provides the mock fixtures table (direct reference). Architectural-principles.md provides boundaries (P4: reasoning never communicates directly with UI; P6: presentation never interprets) that prevent accidentally introducing reasoning logic into UI work. Three-document context (current-project-state, project-knowledge-inventory, document-role-review) is sufficient to route both documents correctly without reading the full experiment log or archive.
|
||||
|
||||
### Files Created / Modified
|
||||
|
||||
- `docs/document-role-review.md` — new (140 lines); classifies both candidates with evidence and routing test
|
||||
- `docs/project-knowledge-inventory.md` — updated "Review Before Archive" table (principle roles added), added "Knowledge management" section with document-role-review entry, updated Return-to-Work note
|
||||
- `docs/current-project-state.md` — updated Return-to-Work note to include Experiment 30 status
|
||||
- No files moved to archive (neither candidate qualifies as "archive as historical evidence")
|
||||
- No files deleted; no source code or tests changed
|
||||
|
||||
### Status
|
||||
|
||||
Pending Rob's review. Neither document moves. Both roles confirmed by evidence against verified implementation. When UI work resumes, backlog info.md's fixtures table will be the direct reference; architectural-principles.md is available for reasoning architecture context. Engine and UI experiments remain paused. Branch: `feature/user-workspace-ux-v0.7`. First file to inspect when resuming: `docs/current-project-state.md`, then Experiments 23–25B in design-evolution-log.md (lines 1218–1520).
|
||||
|
||||
These are observations, not implementation tasks.
|
||||
|
||||
Reference in New Issue
Block a user