ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs: reduce redundant content across files; map references to canonical sources

Browse Source 
Per user 'a bunch of docs just committed had redundant content across
files. Can we do a reduction of that and instead map references to
other files?'

This commit reduces content duplication across 9 files. The
canonical sources are kept as detailed references; the other
files now point to them.

Reductions (table replaced with 'see canonical' reference):

1. data_oriented_design.md §9: the 4-dim memory table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

2. guide_agent_memory_dimensions.md §0: the 4-dim memory table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

3. guide_caching_strategy.md §1: the 12-layer model
   (canonical: conductor/code_styleguides/cache_friendly_context.md §1)

4. guide_ai_client.md 'Cache strategy' section: the 12-layer model recap
   (canonical: conductor/code_styleguides/cache_friendly_context.md §1)

5. guide_knowledge_curation.md §1: the 5 category file details
   (canonical: conductor/code_styleguides/knowledge_artifacts.md §1)

6. product-guidelines.md 'Memory Dimensions' section: the 4-dim table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

7. guide_mma.md '4 memory dimensions' section: the MMA scope table
   (canonical: conductor/code_styleguides/agent_memory_dimensions.md §0)

8. docs/AGENTS.md §0 + §5-§8: 4-dim table + caching/knowledge/RAG/
   feature flag tables (canonical: the per-topic styleguides in
   conductor/code_styleguides/)

9. AGENTS.md 'Code Styleguides' section: the 6-styleguide list
   (canonical: docs/AGENTS.md §2)

The principle: each piece of content has ONE source of truth; other
places point to it. The data-oriented way. Files retain their
narrative flow and the 'what this is' intros, but the detailed
tables are now in their canonical home.

Net effect: -2100 bytes across 9 files (without losing any
information - the canonical sources are unchanged). The
'cross-references' sections are kept; the duplicated content
is removed.
This commit is contained in:
Edward R. Gonzalez
2026-06-12 14:10:30 -04:00
parent 35c6cca134
commit 434b6d0d54
9 changed files with 58 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AGENTS.md
+16 -59
View File
@@ -12,16 +12,11 @@
## 0. The 4 memory dimensions (the cross-cutting lens)
The conversation data has 4 distinct memory dimensions. Most features touch 1-2; some touch 3. Use this lens to identify which dimension(s) your feature needs.
The conversation data has 4 distinct memory dimensions (curation / discussion / RAG / knowledge). Most features touch 1-2; some touch 3. Use this lens to identify which dimension(s) your feature needs.
| # | Dim | Where it lives | Use when | Styleguide |
|---|---|---|---|---|
| 1 | **Curation** | `FileItem` + `ContextPreset` + Fuzzy Anchors | "How to render a file" | (the curation is per `docs/guide_context_curation.md`) |
| 2 | **Discussion** | `app.disc_entries` + branching + UISnapshot | "What was said in this chat" | (the discussion is per `docs/guide_architecture.md` §"Threading model") |
| 3 | **RAG** | `src/rag_engine.py` (ChromaDB) | "What similar content exists" (opt-in) | `conductor/code_styleguides/rag_integration_discipline.md` |
| 4 | **Knowledge** | `~/.manual_slop/knowledge/*.md` + per-file + digest | "What we learned from past sessions" | `conductor/code_styleguides/knowledge_artifacts.md` |
**The full canonical 4-dim table is in `conductor/code_styleguides/agent_memory_dimensions.md` §0** (with the SSDL shape tag per dim). The cross-cutting guide is `docs/guide_agent_memory_dimensions.md`.
See `docs/guide_agent_memory_dimensions.md` for the full cross-cutting guide.
**The one-line summary:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. Pick the matching dimension; don't reach for the wrong shape.
---
@@ -151,21 +146,9 @@ See `docs/guide_agent_memory_dimensions.md` for the full cross-cutting guide.
If the feature builds the initial context (in `aggregate.py:run`) or calls the LLM (in `ai_client.py:send`), the cache strategy matters.
**The 12-layer model:**
**The 12-layer model:** the full table is in `conductor/code_styleguides/cache_friendly_context.md` §1. The short version: layers 1-7 (role, schema, tools, system prompt, persona, project context, knowledge digest) are byte-identical across turns and cacheable; layers 8-12 (discussion metadata, active preset, per-file details, prior tool results, user message) are per-turn and NOT cached. Cache boundary is at layer 7/8.
| # | Layer | Stable across turns? | Where the cache hits |
|---|---|---|---|
| 1-7 | Role instructions, function-calling schema, tool descriptions, system prompt, persona, project context, knowledge digest | **YES** (cacheable) | Anthropic `cache_control`, Gemini `cachedContent`, OpenAI implicit |
| 8-12 | Discussion metadata, active preset, per-file details, prior tool results, user message | **NO** (per turn) | NOT cached |
**The byte-comparison test** (the design contract for the stable prefix):
```python
def test_aggregate_stable_to_volatile_ordering():
"""The first N characters of the context should be identical across turns
of the same conversation, when no stable-layer inputs change."""
...
```
**The byte-comparison test** (the design contract for the stable prefix): the test in `tests/test_aggregate_caching.py` ensures the first N characters of the context are identical across turns. The implementation is `aggregate.stable_prefix_length(ctrl) -> N`. See `conductor/code_styleguides/cache_friendly_context.md` §2.
**The provider-specific TTLs:**
@@ -175,62 +158,36 @@ def test_aggregate_stable_to_volatile_ordering():
| Gemini explicit | 1 h | yes (per-discussion override) |
| OpenAI implicit | 5-10 min (provider-managed) | no |
**The GUI exposure** is a "Caching" Operations Hub sub-panel (per the v2.3 §5.3 sketch). See `docs/guide_caching_strategy.md` for the full guide and `conductor/code_styleguides/cache_friendly_context.md` for the styleguide.
**The GUI exposure** is a "Caching" Operations Hub sub-panel. See `docs/guide_caching_strategy.md` for the full guide and `conductor/code_styleguides/cache_friendly_context.md` for the styleguide.
---
## 6. The knowledge harvest (the durable layer)
The 4th memory dimension (knowledge) is *opt-in but encouraged* — it's the durable, user-editable, provenance-aware store of facts / decisions / questions / playbooks / per-file notes.
The 4th memory dimension (knowledge) is *opt-in but encouraged* — it's the durable, user-editable, provenance-aware store.
**The directory layout** (per the user's `~/.manual_slop/knowledge/`):
**The canonical reference is `conductor/code_styleguides/knowledge_artifacts.md` §0-§4** (the directory layout + the 5 category files + the digest + the ledger + the harvest workflow). The user-facing guide is `docs/guide_knowledge_curation.md`.
```
knowledge/
├── facts.md # - {statement} {provenance}
├── decisions.md # - {statement, reason} {provenance}
├── questions.md # - {question} {provenance}
├── playbooks.md # - **{name}**: {steps} {provenance}
├── tasks.md # ## Open / ## Done
├── files/{file_id}.md # per-file notes (keyed by inode)
├── digest.md # bounded 4KB; the projection; "delete to turn off"
├── ledger.json # sha256-of-content audit log
└── prompts/harvest-conversation.md # user-editable
```
**The harvest CLI:** `python -m src.knowledge_harvest [--apply] [--no-harvest] [--max-harvest-bytes N]`. Default: dry-run.
**The LLM output is strict JSON** (no prose, no markdown fence) with 7 categories. The retry budget is 2 attempts.
**The "delete to turn off" pattern:** `rm ~/.manual_slop/knowledge/digest.md` → no `{knowledge}` block injected. Re-enable by running the harvest.
See `docs/guide_knowledge_curation.md` for the full guide and `conductor/code_styleguides/knowledge_artifacts.md` for the styleguide.
**The one-line summary:** the user can `rm ~/.manual_slop/knowledge/digest.md` to turn off the knowledge injection (file presence as the feature flag). Re-enable by running `python -m src.knowledge_harvest --apply`. The LLM output is strict JSON with 7 categories; the retry budget is 2 attempts.
---
## 7. The RAG discipline (the opt-in fuzzy dimension)
RAG is the *fuzzy semantic search* dimension. It's *opt-in* (default-off in new projects). The 6 rules:
RAG is the *fuzzy semantic search* dimension. It's *opt-in* (default-off in new projects).
1. **Opt-in.** Default-off in new projects
2. **Complements; never replaces.** RAG is one of 4 dimensions, not a substitute
3. **Provenance required.** Every result shows file + chunk
4. **No mutation.** RAG results never write to `disc_entries`, `FileItem`, or disk
5. **Feature-gated.** A feature must explicitly request RAG in its scope
6. **Graceful failure.** Failed search returns empty; the request continues
See `docs/guide_rag.md` for the full RAG guide and `conductor/code_styleguides/rag_integration_discipline.md` for the styleguide.
**The canonical reference is `conductor/code_styleguides/rag_integration_discipline.md`** (the 6 rules: opt-in, complement, provenance, no mutation, feature-gated, graceful failure). The user-facing guide is `docs/guide_rag.md`.
---
## 8. The feature flag patterns (when to use what)
When adding a new feature with an "on/off" toggle, choose the right pattern:
When adding a new feature with an "on/off" toggle, choose the right pattern.
| Pattern | When to use | Example |
|---|---|---|
| **File presence** ("delete to turn off") | The feature produces a side artifact; the user might want to clean up by `rm`-ing it | `~/.manual_slop/knowledge/digest.md` |
| **Config flag** | The feature is always on; the flag is a persistent preference | `[ai_settings.toml] rag.enabled` |
**The canonical reference is `conductor/code_styleguides/feature_flags.md`** (file presence vs config flag vs CLI flag vs track metadata flag; the decision tree; the forbidden patterns). The short version:
- **File presence** ("delete to turn off") — the feature produces a side artifact; the user might want to clean up by `rm`-ing it (e.g., `~/.manual_slop/knowledge/digest.md`)
- **Config flag** — the feature is always on; the flag is a persistent preference (e.g., `[ai_settings.toml] rag.enabled`)
| **CLI flag** | The feature is invoked from the CLI; the flag is a one-shot override | `python -m src.knowledge_harvest --apply` |
| **Track metadata flag** | The track's implementation uses a feature; this is *static documentation* | `metadata.json`: `{"uses_rag": true}` |