View source Markdown

Documentation Audit Ledger

This file records the top 30 improvements identified and applied for each core document.

2026-03-26 Sync Update

This documentation set was re-audited and synchronized with the current implementation after the following system changes:

• GPU-only real Diffusers runtime became the default app path
• mock generation was restricted to explicit test harnesses
• backend and frontend tracing were added and persisted under data/traces/
• per-session HTML trace reports were added under data/traces/sessions/<session_id>/report.html
• async round generation and feedback submission were exposed through job endpoints with visible progress
• a real GPU-backed end-to-end example bundle was added under output/examples/real_e2e_example_run/
• a student-oriented tutorial was added to bridge motivation, theory, and implementation
• the roadmap set was expanded to include image-prompt, inpainting, and ControlNet steering directions
• lifecycle guards were added for duplicate feedback and premature next-round generation
• browser coverage was expanded with headed debug support and replay export API smoke coverage

The most heavily updated documents in this sync were:

• README.md
• quick_start.md
• user_guide.md
• developer_guide.md
• faq.md
• student_tutorial.md
• pre_implementation_blueprint.md
• system_specification.md
• system_test_specification.md

1. Motivation: Top 30 Improvements Applied

1. Added a document-role section so readers know when to use this file.
2. Added links to the related documents for navigation across the spec set.
3. Reframed the introduction around the research problem rather than only system purpose.
4. Made the core problem statement more explicit and concrete.
5. Expanded the list of generation variables that create steering instability.
6. Clarified that the issue is not only prompt sensitivity but also user-control mismatch.
7. Added a crisp central research claim.
8. Separated the central claim from the iterative loop description.
9. Clarified that the goal is to study controllability, not only image quality.
10. Added a section explaining why the project matters beyond curiosity.
11. Split value into research value and practical value.
12. Expanded the research questions into a more useful study agenda.
13. Added a question about fatigue and inconsistency across rounds.
14. Added a question about interface bias and interaction design.
15. Added a section explaining why current interfaces are inadequate for research.
16. Strengthened the rationale for exact reproducibility and replay.
17. Added intended outcomes so the document points toward deliverables.
18. Expanded the goals section to include replay and comparative analysis.
19. Tightened non-goals to reduce scope ambiguity.
20. Renamed the experimental matrix as a first comparison grid to better position it.
21. Clarified that the matrix is intentionally manageable for early research.
22. Added overfitting to one workflow as an explicit confound.
23. Reworded risk statements so they are testable rather than purely descriptive.
24. Added a requirement to log confounds instead of merely acknowledging them.
25. Added explicit success criteria for deciding whether the project is worth continuing.
26. Improved section ordering from problem to claim to value to goals to risks.
27. Made wording more decisive and less repetitive.
28. Improved cross-document consistency with the other spec files.
29. Reduced ambiguity around the research purpose of the platform.
30. Strengthened the summary so it reflects the document's main claim.

2. Theoretical Background: Top 30 Improvements Applied

1. Added a document-role section to define the purpose of the theory doc.
2. Added links back to the motivation and system docs.
3. Clarified that the document is scoped to the minimum theory needed for design.
4. Simplified the diffusion overview without losing technical meaning.
5. Made the consequence of embedding-based conditioning more explicit.
6. Added a dedicated section on why prompt rewriting is hard.
7. Clarified the discrete-text versus continuous-control mismatch.
8. Added explicit mention that prompt rewriting is still useful but limited.
9. Expanded the embedding discussion beyond full-tensor control.
10. Added the notion of tradeoffs among steering representations.
11. Reframed low-dimensional steering as a controllable search space.
12. Added a section explaining why local search is a reasonable framing.
13. Clarified that the system is not solving global optimization.
14. Connected low-dimensional search to interpretability and replay.
15. Strengthened the preference-learning framing.
16. Expanded the list of feedback types to match later system design.
17. Clarified that the latent reward is noisy and only partially observed.
18. Tightened the explanation of exploration versus exploitation.
19. Linked the exploration problem directly to real human attention constraints.
20. Expanded the seed-sensitivity explanation into an identification problem.
21. Made seed-control implications explicit for system design.
22. Added a stronger explanation of trust regions and anchoring.
23. Added a comparison section for multiple representation and update choices.
24. Connected theory choices to concrete engineering consequences.
25. Added a section on the limits of the theory so the document is not overstated.
26. Named entanglement and instability as theoretical limits.
27. Improved continuity between sections by making each one motivate the next.
28. Increased consistency with the terminology used in the system spec.
29. Improved the summary so it restates the practical theoretical justification.
30. Reduced the chance that readers interpret the theory as a claim of guaranteed smoothness.

3. System Specification: Top 30 Improvements Applied

1. Added a document-role section to clarify that this is the main functional contract.
2. Added links to related documents for navigation and alignment.
3. Added an explicit scope section stating what the document does and does not cover.
4. Added a short system-goals section before architecture details.
5. Added a canonical user workflow to anchor the rest of the spec.
6. Added core system invariants that implementation must preserve.
7. Strengthened experiment fields to include steering and control parameters.
8. Strengthened session fields with incumbent reference and status.
9. Strengthened round fields with render status and update summary.
10. Strengthened candidate fields with render status and metadata expectations.
11. Strengthened feedback-event fields with normalized payload requirements.
12. Added lifecycle states for experiments.
13. Added lifecycle states for sessions.
14. Added lifecycle states for candidate rendering.
15. Expanded frontend requirements to include failure behavior.
16. Clarified required dashboard actions and elements.
17. Clarified session-setup inputs and actions.
18. Clarified interactive-page behavior and stable candidate ordering.
19. Tightened accessibility requirements with focus visibility and hover independence.
20. Expanded backend modules to include storage-layer responsibilities.
21. Improved the data model with updated_at, status, and normalized payload fields.
22. Added API conventions in addition to endpoint lists.
23. Added GET /experiments/{experiment_id} for complete experiment retrieval.
24. Clarified response requirements for write endpoints.
25. Tightened the steering-representation section with a default equation explanation.
26. Separated required versus optional samplers and updaters more clearly.
27. Tightened the unified feedback schema language.
28. Added operational constraints for the v1 environment.
29. Updated the suggested project structure to point at system_specification.md.
30. Strengthened the summary around architectural priorities and research use.

4. System Test Specification: Top 30 Improvements Applied

1. Added a document-role section explaining why tests are part of the research method.
2. Added links to the implementation-facing specs.
3. Added explicit test objectives before listing categories.
4. Added a test-environment strategy to reduce unnecessary dependence on real generation.
5. Clarified the distinction between logic, service, and end-to-end tests.
6. Expanded steering unit tests with invalid-dimension failures.
7. Expanded sampler unit tests with role-tag verification.
8. Expanded feedback tests with critique preservation.
9. Expanded feedback tests with skip and uncertain actions.
10. Expanded updater tests with trust-region checks.
11. Expanded seed-policy tests with missing-metadata failure handling.
12. Added persistence and schema unit-test coverage.
13. Strengthened the generation integration test to cover partial success.
14. Strengthened the replay integration test to include round-order stability.
15. Split sampler and updater swap checks explicitly in plug-in tests.
16. Added API contract integration tests.
17. Expanded end-to-end coverage to require at least two feedback modes.
18. Expanded end-to-end coverage to include replay opening.
19. Added recoverable-error display checks to end-to-end tests.
20. Strengthened deterministic replay checks with round summaries.
21. Added a separate regression-test section.
22. Added edge-case prompt regression coverage.
23. Added edge-case feedback-payload regression coverage.
24. Added replay-bug regression coverage.
25. Added an explicit failure-mode test section.
26. Added export-failure testing.
27. Added database interruption and resume testing.
28. Expanded fixtures with schema snapshots.
29. Strengthened acceptance criteria with failure-mode coverage.
30. Added test-reporting expectations so failures are easier to interpret.

5. Pre-Implementation Blueprint: Top 30 Improvements Applied

1. Added a document-role section to frame this as an implementation handoff.
2. Added links to the related research and test docs.
3. Added implementation principles before scope details.
4. Reframed v1 scope as a concrete engineering boundary.
5. Tightened out-of-scope items to reduce future drift.
6. Added a clear assumptions section to lock environment defaults.
7. Added a requirement for mock generation during testing.
8. Reworked open decisions into decisions that should be fixed before coding.
9. Kept default-model choice explicit and actionable.
10. Kept default-basis choice explicit and actionable.
11. Kept default-feedback choice explicit and actionable.
12. Kept default-updater choice explicit and actionable.
13. Clarified frontend responsibilities versus non-responsibilities.
14. Clarified backend responsibilities versus non-responsibilities.
15. Clarified storage responsibilities and exclusions.
16. Strengthened the session contract before implementation.
17. Strengthened the candidate contract before implementation.
18. Strengthened the feedback contract before implementation.
19. Strengthened the replay contract before implementation.
20. Renamed implementation order to delivery order for clearer project planning.
21. Tightened minimal API decisions as pre-coding agreements.
22. Expanded non-functional requirements for reproducibility.
23. Expanded non-functional requirements for debuggability.
24. Expanded non-functional requirements for modularity.
25. Reworked risk sections into explicit risk-and-mitigation pairs.
26. Added a clearer definition of implementation readiness.
27. Added delivery milestones to make the blueprint easier to execute.
28. Improved consistency of terminology with the system spec.
29. Reduced ambiguity around what must be decided before coding starts.
30. Strengthened the summary so the document reads as an actual handoff artifact.