# nagent_takeaways_v3_1_20260620 — Bridge to v3 takeaways + sibling reviews

**Date:** 2026-06-20
**Spec pair:** `spec_v3.1.md` + `plan_v3.1.md`
**Companion:** `nagent_review_v3_1_report_20260620.md` (the v3.1 thickened main review); `comparison_table.md` (v3.1 cluster table); `decisions.md` (v3.1 candidate list); `nagent_takeaways_v3_20260619.md` (the v3-era bridge; preserved unchanged); `nagent_review_v3_20260619.md` (the v3 main review; preserved unchanged per user directive 2026-06-20).
**Source:** nagent v3.1 (`a1f0680` on `macton/nagent@main`, 2026-06-18) + the two case-study repos at `main` + user's 3 new observations (YAML avoidance, agent context-window, fine-tuning).

> **File-naming note (user directive 2026-06-20).** The v3.1 thickened content is in a NEW file (`nagent_review_v3_1_report_20260620.md`), not in `nagent_review_v3_20260619.md` (the v3 main review, which is preserved unchanged). The delta summary is `nagent_review_v3_1_20260620.md`. See `metadata.json` `v3_1_file_separation` field for the file structure.

5-part structure: TL;DR + cross-reference table + new v3.1 candidates + v3 candidates v3.1 supersedes + sibling-review pointer.

---

## 1. TL;DR

v3.1 is the **delta thickening** of the v3 review: per-cluster expansion (via the chunking strategy, per `spec_v3.1.md` §4.1) + 3 new top-level sections (§12 YAML avoidance, §13 Agent context-window observations, §14 Fine-tuning observations) + refreshed side artifacts (comparison_table, decisions, this bridge doc). The v3 main review is preserved unchanged (per the user's 2026-06-20 directive). The v3.1 thickened content lives in `nagent_review_v3_1_report_20260620.md`. v3.1 preserves the v3 candidate pool (Candidates 17-26) and adds 4 new candidates (27-30) from the new observations.

---

## 2. Cross-reference table

| v3.1 takeaway | Touches v3 candidate | Section |
|---|---|---|
| Markdown + custom DSL lock-in (Candidate 27) | 17 (Campaign-style plan-as-data) | §12 |
| Per-turn ground-truth hook reframing (Candidate 28) | 19 (Per-turn ground-truth hook) | §13 |
| Warm-up + window + safe-zone cycle | 18 (Discussion-window safety net) | §13 |
| Cache TTL GUI contract hardening (Candidate 30) | 12 (Cache TTL GUI controls) | §14 |
| Dataset-curation track for fine-tuning (Candidate 29) | 16 (AGENTS.md @import + canonical DOD file) | §14 |
| Q9 expansion ("different machine?") is a fine-tuning target | 24 (Document Q9 in project DOD styleguide) | §14 + §8 |
| Per-turn hook is the structural mechanism for the cycle | 19 (Per-turn ground-truth hook) | §13 + §3 |
| Markdown + DSL is the project's convention per `intent_dsl_survey_20260612` | n/a (project convention) | §12 |
| Markdown + DSL is the project's convention per `superpowers_review_20260619` | n/a (project convention) | §12 |
| nagent's case-study methodology is a 5-element pattern | 25 (Optimization-log discipline), 26 (`OPTIMIZATION-LOG` schema) | §9 + §10 + §11 |
| nagent's safety net is the structural mechanism for the cycle | 18 (Discussion-window safety net) | §2 + §13 |
| nagent's per-turn hook closes Manual Slop's "agents forget to read" gap | 19 (Per-turn ground-truth hook) | §3 + §13 |
| nagent's Q9 expansion ("different machine?") is a load-bearing new question | 24 (Document Q9 in project DOD styleguide) | §8 |
| nagent's per-type specialization is a Q9 application | 27 (Tolerance-based comparator) | §11 |
| nagent's `OPTIMIZATION-LOG.md` is a portable schema | 25 (Optimization-log discipline) | §9 + §10 + §11 |

---

## 3. The new v3.1 candidates (Candidates 27-30)

### Candidate 27 (HIGH): Markdown + custom DSL lock-in

**Verdict evidence:** v3.1 §12 catalogs every YAML use site in nagent (campaigns, distill, knowledge, graduates) and flags them as "do not adopt" for Manual Slop. The markdown + DSL alternative is concrete: each campaign-style artifact becomes a markdown file with structured headings + a TOML frontmatter block (project config precedent) + optional SSDL-annotated code blocks for any inline computation. The TOML frontmatter is the `conductor/presets.py` + `conductor/personas.py` precedent; the markdown body is the project convention; the SSDL annotations are the `intent_dsl_survey_20260612` Cluster 5 primitives.

**Why HIGH:** the format commitment is project-wide; affects every future conductor track + every styleguide + every project doc. The YAML-avoidance is a "do not adopt" flag, not a "must not exist" ban — the user can still read and parse YAML (e.g., when reading nagent's source), but new Manual Slop artifacts use markdown + DSL.

### Candidate 28 (MEDIUM): Per-turn ground-truth hook for Manual Slop (reframing of Candidate 19)

**Verdict evidence:** v3.1 §13 captures the user's empirical findings (warm-up ~100-150k; window up to ~500k MiniMax M3; safe zone 250-350k; compact→re-warm→continue cycle) and notes that Manual Slop's `docs/` + `conductor/` markdown navigation is a partial mitigation. The shortcoming is that agents frequently forget to read or fail to read on demand. nagent's `--hook-per-run` pattern is the structural mechanism that closes the gap. The Candidate 19 is amended: the hook is not just a status command, but a structured "what to read next" status block that surfaces the relevant guidance for the current task.

**Why MEDIUM:** the abstraction is generalizable; Manual Slop already has analogous hooks (Tier 4 QA error interception per `docs/guide_ai_client.md`). The per-turn hook closes all three failure modes: (1) forget to read, (2) fail to read on demand, (3) read but ignore.

### Candidate 29 (MEDIUM): Dataset-curation track for fine-tuning

**Verdict evidence:** v3.1 §14 captures the diagnosis (current generalized models are bottlenecked by not having the user's core conventions/workflows baked in) + the user's interest in fine-tuning as the mitigation + the Together.ai observation + 5-6 other prosumer fine-tuning vendors surveyed (Together.ai, Fireworks.ai, OpenAI 4o-mini, Anthropic Haiku, Gemini Flash, local Unsloth).

**Why MEDIUM:** the dataset is the user's call; the vendor selection is a separate effort; the validation is a separate effort. The v3.1 §14 section is the marker; the implementation is a future track.

### Candidate 30 (LOW): Cache TTL GUI contract hardening

**Verdict evidence:** v3.1 §14 cross-refs `cache_friendly_context.md` (the cache TTL GUI contract). The hardening is a small change to the per-turn hook (Candidate 28): the hook block includes cache state (which files are in cache, which are invalidated, the cache TTL, etc.) so the model responds against the cache state in addition to the other measured state.

**Why LOW:** small change; sub-pattern of Candidate 28. The cross-ref to `cache_friendly_context.md` is the canonical reference; a future track would add cache-state tracking to the per-turn hook.

---

## 4. The v3 candidates v3.1 supersedes (0)

The v3.1 amendments to v3 candidates are *extensions* of the v3 candidates, not *supersedes*. No v3 candidate is fully superseded by v3.1; the v3.1 amendments add v3.1-specific framing (markdown + DSL, per-turn hook, fine-tuning) to the existing v3 candidates.

The v3.1 amendments:

- **Candidate 17** (Campaign-style plan-as-data) — amended by Candidate 27: the artifact format is markdown + frontmatter, not YAML.
- **Candidate 19** (Per-turn ground-truth hook) — reframed by Candidate 28: the hook is not just a status command, but a structured "what to read next" status block.
- **Candidate 12** (Cache TTL GUI controls, sub-candidate 12b) — refined by Candidate 30: the per-turn grounding primitive also tracks cache state.
- **Candidate 16** (AGENTS.md @import + canonical DOD file) — extended by Candidate 29: the Q9 expansion is a candidate for the fine-tuning dataset.

The amendments are *extensions*, not *supersedes*. The v3 candidates stand; the v3.1 amendments add context-specific framing.

---

## 5. Sibling-review pointer

- **`fable_review_20260617`** — Fable's analysis of Mythos system prompt. Touchpoint: v3.1 §8 (Operating rules) is the data-oriented response to Fable's persona-based "watch-dogging" anti-pattern. The Q9 expansion ("different machine?") is the data-oriented alternative to Fable's "be careful" persona framing.
- **`intent_dsl_survey_20260612`** — the 10 prior-art clusters for intent-based DSLs. Touchpoints: v3.1 §9 (Case-study methodology) is implicitly an intent-DSL for "drive nagent at an optimization problem" (the survey's Cluster 4 "Meta-Tooling DSLs" + Cluster 3 "intent-mapping" are the closest prior art); v3.1 §12 (YAML avoidance) cites the survey's Cluster 5 "SSDL shape primitives" as the project's DSL primitive.
- **`superpowers_review_20260619`** — the superpowers plugin review. Touchpoints: v3.1 §9 (Case-study methodology) — the superpowers `brainstorming` skill is a process parallel (structured questions to refine an idea before implementation, same role as the case-study 4 prompts); v3.1 §12 (YAML avoidance) — the superpowers review establishes the project's markdown-driven conventions (the 6 styleguides in `conductor/code_styleguides/` are markdown; the 14 deep-dive guides in `docs/` are markdown); v3.1 §13 (Agent context-window observations) — the markdown navigation is the project's partial mitigation for the cycle.

Plus project-file references that capture the v3.1 observations:

- **`conductor/code_styleguides/cache_friendly_context.md`** — the cache TTL GUI contract (referenced by v3.1 §13 + §14 for the per-turn hook + cache TTL hardening).
- **`conductor/presets.py` + `conductor/personas.py`** — the TOML precedent for project config (referenced by v3.1 §12 for the markdown+DSL alternative).
- **`conductor/code_styleguides/data_oriented_design.md`** — the canonical DOD reference (referenced by v3.1 §8 for the Q9 expansion; the Q9 expansion is a candidate for fine-tuning per v3.1 §14).
- **`docs/guide_meta_boundary.md`** — the Application vs Meta-Tooling distinction (load-bearing context for the v3.1 verdict structure).
- **`AGENTS.md`** — the canonical operating instructions for agents (the project convention; referenced by v3.1 §13 as the per-turn hook's "what to read next" surface).
