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:
2026-08-06 14:33:10 +01:00
parent 97e4f3029e
commit 78c98fb973
4 changed files with 197 additions and 5 deletions
+47
View File
@@ -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 14 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 2325B in design-evolution-log.md (lines 12181520).
These are observations, not implementation tasks.