13 KiB
Document Role Review — Experiment 30
1. Review Method
Documents reviewed (as constrained):
docs/current-project-state.md(entire file)docs/current-implementation-verification.md(entire file)docs/project-knowledge-inventory.md(Task-Specific References, Historical and Archive Candidates, Gaps and Duplications)docs/archive/README.md(archive rules only)docs/architectural-principles.md(entire file)docs/backlog info.md(entire file).claude/architecture-guardrails.md(entire file)docs/design-evolution-log.mdExperiment 29 entry (lines 1703–1761)
Classification criteria: Each candidate was assessed against current-project-state's verified active/passive capability list, implementation-verification's cross-module traces, project-knowledge-inventory's stated roles, and architecture-guardrails' current invariants. A principle is "current" if it matches a confirmed runtime pattern or guardrail. "Aspirational" if the target exists but no working implementation drives it yet. "Duplicated" if it restates content found more concisely in another document. "Unclear/outdated" if its source experiment or implication cannot be verified against current state.
2. Architectural Principles Review
Current principles (match verified implementation or guardrails)
| Principle | Status | Evidence |
|---|---|---|
| P1 — Every Layer Has One Responsibility | Current | Passive classifiers are isolated modules; orchestrator imports them separately. Matches guardrails' separation discipline. |
| P3 — Feedback Flows Upward Through the User | Current | Product is "facilitated investigation"; turn cycle confirms user-driven feedback loop. |
| P4 — Reasoning Never Communicates Directly With the UI | Current | Narrative layer exists as contract; guardrails enforce separation explicitly. |
| P6 — Presentation Never Interprets | Current | v0.7 UX panels driven by narrative; no panel reimplements filtering. Matches guardrails. |
| P8 — Narrative Never Invents Facts | Current | Core invariant in architecture-guardrails. Traced to runtime narrative adapter. |
| P14 — The User Is Part of the Architecture | Current | v0.7 UX design and product direction confirm user as first-class participant. |
Aspirational principles (target exists but not fully implemented)
| Principle | Status | Evidence |
|---|---|---|
| P5 — Behaviour Never Reasons | Aspirational | behaviour-selection module exists but has zero callers outside its own file. Target is defined; runtime enforcement pending. |
| P7 — Assessment Never Generates Evidence | Mixed | assessment layer is diagnostic_only (verified). However, scope-aware condition status makes interpretive judgments about evidence direction — bordering on generating new claims. |
| P9 — Assessment Describes, Never Prescribes | Mixed | Signals are currently descriptive in the assessor, but decision-condition status evaluates "support/contradict/inform" which moves toward prescription. Partially implemented. |
| P10 — Convergence Over Single Signals | Aspirational | Passive classifiers produce multiple dimensions but no explicit convergence logic exists. Target stated; no mechanism. |
| P11 — Assessment Is Stateful Across Turns | Mixed/Aspirational | Assessor exists and tracks per-turn state, but cross-turn accumulation (deltas, trends) is not verified against the current assessor output shape. Partial at best. |
| P12 — Uncertainty About Assessment Is Itself Assessable | Aspirational | No confidence-per-dimension field visible in the assessor output. Concept stated; mechanism absent. |
| P13 — Investigation Progress Is Qualitative Not Quantitative | Mixed/Aspirational | Product direction states "quality over quantity." Unknown selection uses graph node status (qualitative) but is not verified to explicitly reject count-based progress. Partial match. |
Duplicated principles
- P1 overlaps with architecture-guardrails' hard boundaries (each layer one responsibility is implicit in guardrails' exhaustive prohibition list).
- P4 overlaps with architecture-guardrails' explicit boundary list for UX tasks (reasoning code must not be modified during UI work).
- P8 overlaps with the invariant "Every user-facing question comes from an explicit unresolved graph node" and narrative layer's documented purpose in project-knowledge-inventory.
No principle is wholly duplicated — all retain value as articulated principles, but three overlap with guardrails content that is more operationally concise.
Unclear or outdated statements
- P2 — Information Flows Downward: The principle describes an ideal data flow that partially matches (graph → narrative → ...), but the passive classifier layers (evidence direction, scope detection) operate laterally rather than in the described cascade. Documented as "unresolved" in current-project-state section 5 regarding how these layers integrate. Not outdated — unresolved.
- The header line "Architecture Experiment 17" is accurate for origin but does not note that principles extend through Experiments 1–17 and have been partially validated by later experiments (18–25B). No correction needed; the header is historical provenance.
Recommended document role: Keep as task-specific reference
Evidence for recommendation
- Six principles are current and useful when reviewing or resuming reasoning architecture work.
- Four principles are aspirational but define clear targets — they are valuable as goals for future engineering.
- Three principles overlap with architecture-guardrails but add explanatory context (derived-from, implications) that guardrails lack. Guardrails state the boundary; principles explain why.
- The document is 306 lines of structured reasoning history — too long to load by default but valuable when a task involves reasoning architecture or design justification.
- project-knowledge-inventory already lists it as "Review Before Archive (may have future value)." This experiment confirms that assessment: the principles are neither purely current nor purely historical — they are a reference with mixed provenance, best kept where it is but labeled clearly for future Claude sessions.
3. Backlog Information Review
Still-relevant content
- Mock fixtures table (15 rows): The list of scenario types and their purposes remains valid as a UI mock development reference. These fixture categories map to actual investigation states that need testing when UI work resumes.
- "Deliberately Out of Scope" section: Correctly documents the current product boundary — reasoning engine expansion is deferred while UX experience is prioritized. This matches current-project-state section 6 (both engine and UI paused) and product direction in project-context.
Historical content
- Phase 1–4 UX roadmap: Detailed UX wireframe text (history format, understanding card, loading messages, animation specs). These are aspirational design notes from a specific development phase that is now paused. The intent is valid; the specifics may change when UI work resumes.
- Backlog section (reasoning replay): A high-level feature idea without implementation specification or priority. Historical UX thinking, not actionable engineering work.
Duplicated content
- Phase 4 ("Mock Scenario Library") duplicates the fixtures table at the top of the file — same scenarios listed twice with different formatting.
- "Deliberately Out of Scope" repeats the pause decision already documented in current-project-state section 6 and project-context.md.
Unclear ownership or status
- The mock fixtures table has no owner and no associated ticket. It is a reference artifact from UX development, not an active task list.
- None of the roadmap phases are linked to commits, PRs, or experiments. They represent design intent from a paused phase, not tracked work items.
Recommended document role: Retain temporarily pending revision
Evidence for recommendation
- The mock fixtures table (≈20 lines) is directly useful when UI work resumes and would be harder to locate if moved to archive.
- The UX roadmap content (≈370 lines) is largely aspirational design notes from a paused phase — not current guidance, not actionable backlog, not historical evidence of decision-making. It is deferred UX planning.
- Moving the entire document to archive would make the mock fixtures harder to find during future UI work.
- Archiving just the roadmap portion would require splitting the file (not permitted by constraints).
- The best immediate action is to record its mixed role and leave it in place until a future experiment handles selective revision or archival of its contents.
4. Recommended Actions
| Document | Action | Rationale |
|---|---|---|
docs/architectural-principles.md |
Keep as task-specific reference | Principles are neither purely current nor purely historical. Six are verified current; four are clear targets; three overlap with guardrails but add context. Valuable when resuming reasoning work; not needed by default. project-knowledge-inventory already classified it this way. No correction needed. |
docs/backlog info.md |
Retain temporarily pending revision | Contains a useful mock fixtures table (UI reference) mixed with deferred UX planning notes (aspirational, untracked). Splitting the file or archiving parts requires revising content (constraints forbid this). Its dual role needs resolution when UI work resumes. project-knowledge-inventory already classified it this way. No correction needed. |
Neither document qualifies for "archive as historical evidence" because both contain material with potential near-term utility (principles as reasoning targets; mock fixtures as UI reference). Neither qualifies for "keep as current guidance" because significant portions are aspirational or deferred.
5. Questions That Remain
- Should architectural-principles.md be updated to annotate each principle as [Current]/[Aspirational] rather than leaving this classification implicit? (Requires modifying the document — deferred.)
- Should backlog info.md's mock fixtures table be extracted into a separate file when UI work resumes, to avoid carrying 370 lines of UX planning alongside a 15-row reference? (Deferred to UI resumption.)
- Does any active code path depend on content from either document? (No — verified via implementation-verification cross-module traces showing zero dependencies on architectural-principles.md or backlog info.md by any source module.)
Practical Routing Test
Scenario: A future Claude session is about to work on UI mocks.
Answer: Read both architectural-principles.md and backlog info.md.
Why:
backlog info.mdprovides the mock fixtures table (15 scenarios with purposes) — the direct reference for building mock investigations.architectural-principles.mdprovides context on how reasoning and UI should interact (P4: reasoning never communicates directly with UI; P6: presentation never interprets), which guards against accidentally introducing reasoning logic into UI mock development.
Sufficiency of three-document context: Yes. project-knowledge-inventory.md identifies both files as task-specific references for their respective domains (principles for architecture, backlog fixtures for UX). current-project-state.md confirms UI is paused but workspace layout design intent remains documented. document-role-review.md confirms neither file should be loaded by default but each serves a distinct reference role when the specific task domain is active. Together they answer: what exists to load, why it matters, and how to use it without reading the full experiment log or archive.
Return-to-Work Note
The two deferred documents from Experiment 29 were reviewed because their current value was uncertain — neither could be confidently archived without understanding whether their content still matched verified implementation. architectural-principles.md was assigned the role of task-specific reference: six of fourteen principles are verified current against runtime, four are clear aspirational targets, three overlap with guardrails but add valuable context. It remains in docs/. backlog info.md was assigned retain temporarily pending revision: it mixes a useful mock fixtures table (15 scenarios) with deferred UX planning notes (370 lines of aspirational design). Both documents stay in place; neither moved to archive because both contain material with potential near-term utility when their respective work domains resume. Future sessions working on reasoning architecture should load architectural-principles.md as reference. Future sessions working on UI mocks should load backlog info.md for fixture references. 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 consult the inventory for task-specific references.