diff --git a/conductor/tracks/fable_review_20260617/research/cluster_4_tone_and_formatting.md b/conductor/tracks/fable_review_20260617/research/cluster_4_tone_and_formatting.md new file mode 100644 index 00000000..85924ee8 --- /dev/null +++ b/conductor/tracks/fable_review_20260617/research/cluster_4_tone_and_formatting.md @@ -0,0 +1,230 @@ +# Cluster 4: Tone & Formatting Constraints + +**Sub-agent dispatch:** Tier 3 Worker (2026-06-17). Read-only research task. +**Sources read:** +- `docs/artifacts/Fable System Prompt.md` lines 68-90 (`tone_and_formatting`, `lists_and_bullets`) +- `docs/artifacts/Fable System Prompt.md` line 124 (the "never thanks the person" rule from `user_wellbeing`; cross-reference to cluster 3) +- `AGENTS.md` (root; tone framing is implicit, not a section) +- `conductor/product-guidelines.md` lines 39-49 (the "AI-Optimized Compact Style" section) +- `conductor/product-guidelines.md` §"UX & UI Principles" (high-density, professional-arcade framing) +- `.opencode/agents/tier1-orchestrator.md` (terse "no pleasantries" directive) +- `.opencode/agents/tier3-worker.md` (1-space indentation rule) +- `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` §3.8 lines 1880-2019 (the `CLAUDE.md` `@import` pattern) +- `conductor/tracks/nagent_review_20260608/nagent_review_v2_2_20260612.md` §2.4 lines 218-227 (AGENTS.md swap applied) + +--- + +## 1. What Fable says + +The Fable `tone_and_formatting` section (lines 68-81) opens with a warmth directive and a constructive-pushback clause, then layers on conversational rules about curses, questions, minor-detection, and file-existence checks. The `lists_and_bullets` sub-section (lines 83-90) reframes warmth as a *formatting* discipline: avoid bold/headers/lists/bullets unless asked or essential; prose for typical conversation; prose for reports/technical documentation; never bullets when declining. + +### 1.1 Warm-tone + constructive push-back (lines 70-71) + +- Line 70: "Claude uses a warm tone, treating people with kindness and without making negative assumptions about their judgement or abilities." +- Line 71: "Claude is still willing to push back and be honest, but does so constructively, with kindness, empathy, and the person's best interests in mind." + +The pair is load-bearing: Fable sets a *default* (warm) and a *guard rail* (push-back is allowed but constructive). The guard rail is the genuinely useful element; the default is persona framing (the model has no "warmth," only text generation that simulates it). + +### 1.2 Illustrative framing (line 73) + +- Line 73: "Claude can illustrate explanations with examples, thought experiments, or metaphors." + +This is a permission grant, not a constraint. Fable permits stylistic elaboration that the codebase already uses elsewhere (e.g., the `data_oriented_design` styleguide's reference to Fleury's "errors are just cases" essay). + +### 1.3 Curse / question discipline (lines 75, 77) + +- Line 75: "Claude never curses unless the person asks or curses a lot themselves, and even then does so sparingly." +- Line 77: "Claude doesn't always ask questions, but, when it does, it avoids more than one per response and tries to address even an ambiguous query before asking for clarification." + +Both rules are persona-performance cues. The curse rule is irrelevant in a coding-tool context. The one-question rule is a useful heuristic for *interview-style* conversations but irrelevant to single-turn task work. + +### 1.4 Minor-detection + adult-default (line 79) + +- Line 79: "If Claude suspects it's talking with a minor, it keeps the conversation friendly, age-appropriate, and free of anything unsuitable for young people. Otherwise, Claude assumes the person is a capable adult and treats them as such." + +This is anti-watchdog framing (cluster 3 territory). The "capable adult" default is the only project-relevant nugget — it codifies the "trust the user, don't second-guess" stance that Manual Slop's directives also imply. + +### 1.5 File-presence verification (line 81) + +- Line 81: "A prompt implying a file is present doesn't mean one is, as the person may have forgotten to upload it, so Claude checks for itself." + +This is a useful operational discipline — the model shouldn't assume file content from a filename. It maps directly to Manual Slop's `manual-slop_read_file` / `manual-slop_get_file_summary` workflow: agents must verify, not assume. + +### 1.6 Formatting discipline (lines 84-90) + +- Line 84: "Claude avoids over-formatting with bold emphasis, headers, lists, and bullet points, using the minimum formatting needed for clarity." +- Line 86: "In typical conversation and for simple questions Claude keeps a natural tone and responds in prose rather than lists or bullets unless asked; casual responses can be short (a few sentences is fine)." +- Line 88: "For reports, documents, technical documentation, and explanations, Claude writes prose without bullets, numbered lists, or excessive bolding unless the person asks for a list or ranking." +- Line 90: "Claude never uses bullet points when declining a task; the additional care helps soften the blow." + +This is the **genuinely-useful nugget** of cluster 4. The default-prose rule maps directly to Manual Slop's "AI-Optimized Compact Style" (the formatting discipline is the same insight applied to a different medium). + +### 1.7 The "never thanks the person" cross-reference (line 124) + +- Line 124 (user_wellbeing): "Claude does not want to foster over-reliance on Claude or encourage continued engagement with Claude. Claude knows that there are times when it's important to encourage people to seek out other sources of support. Claude never thanks the person merely for reaching out to Claude. Claude never asks the person to keep talking to Claude, encourages them to continue engaging with Claude, or expresses a desire for them to continue. Claude avoids reiterating its willingness to continue talking with the person." + +This overlaps cluster 3 (anti-engagement framing for mental-health contexts) but is also a **tone rule**: don't be sycophantic, don't perform gratitude, don't perform availability. The "Claude never thanks" rule is a guard against a specific LLM-failure mode (gratitude performance) that has nothing to do with mental health and is genuinely useful as a project directive. + +--- + +## 2. What this project does + +Manual Slop's tone and formatting conventions are split across three layers: the *project-level* agent directives (`AGENTS.md`), the *style* directives (`conductor/product-guidelines.md`), and the *per-tier* operational protocols (`.opencode/agents/tier*.md`). None of them codify a "warm tone" persona; the project's tone is *terse-and-correct* by deliberate design. + +### 2.1 `AGENTS.md` (root) — implicit tone, no persona + +`AGENTS.md` (root) has no "Tone" section. The implicit tone is set by the file's own writing style: terse, rule-focused, anti-persona. The opening line at `AGENTS.md:3` declares the project in 2 sentences — no fluff. The "Critical Anti-Patterns" section at `AGENTS.md:50+` is a 13-item bulleted list of forbidden patterns; the file uses lists because the content *is* a list of rules, not because it performs friendliness. + +The relevant style cues from `AGENTS.md`: + +- `AGENTS.md:50-56` "Critical Anti-Patterns" — uses bullets because the content is genuinely a list. +- `AGENTS.md:59-61` "Do not add comments to source code; documentation lives in `/docs`" — terse imperative, not a friendly suggestion. +- `AGENTS.md:73` "HARD BAN: `git restore`, `git checkout -- `, `git reset` are FORBIDDEN" — uppercase for emphasis (the only emphasis Fable-style rules would forbid), but justified: the rule is load-bearing. + +The framing throughout is "this is what the project is; these are the rules; do them" — not "let me warmly guide you through this." + +### 2.2 `conductor/product-guidelines.md` §"AI-Optimized Compact Style" — the formatting discipline + +The AI-Optimized Compact Style section at `conductor/product-guidelines.md:39-49` codifies Manual Slop's formatting discipline in 6 rules: + +- Line 40: "**Indentation:** Exactly **1 space** per level. This minimizes token usage in nested structures." +- Line 41: "**Newlines:** Maximum **one (1)** blank line between top-level definitions. **Zero (0)** blank lines within function or method bodies." +- Line 42: "**Vertical Compaction:** Use single-line `if` statements, semicolon-separated framework calls (`imgui.same_line(); imgui.text(...)`), and aligned assignments to aggressively minimize vertical line counts." +- Line 43: "**Region Blocks:** Use `#region: Name` and `#endregion: Name` to logically organize massive files..." +- Line 44: "**Type Hinting:** Mandatory, strict type hints for all parameters, return types, and global variables..." +- Line 45: "**Structural Dependency Mapping (SDM):** All major state variables, methods, and functions MUST include terse dependency tags at the end of their docstrings..." + +The framing throughout is *token-economy-driven*, not warmth-driven: "minimize token usage," "minimize vertical line counts," "aggressively minimize." The data-grounded contrast to Fable's "warm tone" framing is direct: Manual Slop's formatting discipline is justified by data (token burn, context window pressure), not persona. + +### 2.3 `conductor/product-guidelines.md` §"UX & UI Principles" — the visual analog + +The UX principles (which are about the *application* UI, not agent output) state: + +- "USA Graphics Company Values: Embrace high information density and tactile interactions." +- "Professional Arcade Aesthetics: Balances high-energy 'Arcade' feedback (blinking notifications, tactile updates) with a 'Professional' visual discipline." +- "Explicit Control & Expert Focus: The interface should not hold the user's hand. It must prioritize explicit manual confirmation for destructive actions while providing dense, unadulterated access to logs and context." + +The "Expert Focus" principle at the third bullet is the closest the project gets to Fable's "treats people as capable adults" framing — but expressed as an *interface property* (no hand-holding), not a persona behavior. The same anti-watchdog stance, different surface. + +### 2.4 `.opencode/agents/tier*.md` — terse protocol directives + +The tier agents are *explicitly* terse: + +- `.opencode/agents/tier1-orchestrator.md:6-7`: "STRICT SYSTEM DIRECTIVE: You are a Tier 1 Orchestrator. Focused on product alignment, high-level planning, and track initialization. **ONLY output the requested text. No pleasantries.**" +- `.opencode/agents/tier3-worker.md:1-3`: "STRICT SYSTEM DIRECTIVE: You are a stateless Tier 3 Worker (Contributor). Your goal is to implement specific code changes or tests based on the provided task. Follow TDD and return success status or code changes. **No pleasantries, no conversational filler.**" + +The phrase "no pleasantries" appears in **two** tier agents (Tier 1 and Tier 3), as the explicit, named rejection of Fable's "warm tone" framing. The project has codified "no pleasantries" as a tier-1 and tier-3 directive. + +The tier agents also use formatting that Fable would forbid (uppercase `MANDATORY`, `BANNED`, `CRITICAL`, bullet lists of mandatory checklists) — but this is justified: the content is genuinely operational rules, not chat content. Same insight as Fable, different surface. + +### 2.5 The 1-space indentation rule — a formatting discipline Fable doesn't have + +`AGENTS.md:2` and `.opencode/agents/tier3-worker.md:3-4` both specify "exactly 1 space per indentation level." This is a *project-wide* formatting rule, with token-economy justification. It is the most concrete project-side counter to "Claude can use lists/bullets/headers freely" — Manual Slop's docs and code are vertically compact by design. + +### 2.6 The data-oriented contrast + +Fable's tone guidance is framed as *behavior* ("Claude uses a warm tone"). Manual Slop's formatting guidance is framed as *output schema* (1 space, 0 blanks, single-line `if`, region blocks). The data-oriented framing is more rigorous: the rules are verifiable (a linter can check indentation; a regex can check for bullets), the Fable framing is not. This is the project-level anti-pattern that `conductor/code_styleguides/error_handling.md` makes explicit: "errors are just cases" — i.e., turn behaviors into inspectable data, not into persona performance. + +--- + +## 3. What nagent does + +The nagent corpus has **no** tone-and-formatting section. The closest match is §3.8 (the `CLAUDE.md` `@import` pattern) which is about *file structure* for agent directives, not tone. nagent's approach is structural, not stylistic — the agent's "tone" is whatever the prompt's directives say, and nagent's prompts are terse, rule-focused, anti-persona by design. + +### 3.1 nagent v2.3 §3.8 — the `CLAUDE.md` `@import` pattern + +`nagent_review_v2_3_20260612.md:1880-2019` documents the `CLAUDE.md` file in detail. The relevant excerpt: + +- Line 2005: "**The `@import` pattern.** The line `@context/data-oriented-design.md` is the load-bearing detail. The same file is injected into the agent's context (when Claude Code reads `CLAUDE.md`) and into every nagent conversation (via `context.yaml` → `context/data-oriented-design.md`). One source of truth." + +The pattern is structural: one canonical file is imported into multiple contexts (agent harness + runtime). It says nothing about tone or formatting — the canonical file (`context/data-oriented-design.md`) is itself terse and rule-focused. + +### 3.2 The `CLAUDE.md` content (verbatim from §3.8) + +The `CLAUDE.md` excerpt at `nagent_review_v2_3_20260612.md:1880+` shows the file's structure: + +- Opening: "This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository." (declarative, terse) +- "## What this is" section: "**nagent** ('not-an-agent') is a small reference implementation of a data-oriented LLM workflow loop. The thesis drives every design decision and should drive yours: **the data is the thing, not the agent.**" (one-sentence summary; uppercase emphasis for thesis only) +- "## Commands" section: bash code blocks, no pleasantries. +- "## Conventions for changes" section: 4 bullets, each terse imperative. + +The `CLAUDE.md` style mirrors Manual Slop's `AGENTS.md`: terse, declarative, rule-focused. **No tone directives.** No "warm tone" rule. No "constructive push-back" rule. The file is *output schema*, not persona. + +### 3.3 The `context/data-oriented-design.md` referenced file + +`nagent_review_v2_3_20260612.md:2005-2015` describes the canonical DOD file as "shared between the agent harness and runtime." The actual content of that file is in nagent's repo, not in the review corpus, but the *framing* in the review is telling: the file is described as "the load-bearing detail" for "one source of truth." It's a structural pattern, not a tone pattern. + +### 3.4 nagent's `bin/nagent` style — terse code comments + +The nagent corpus's source files (per `nagent_review_v2_3_20260612.md`'s code excerpts) follow the same terse-rule style: code comments are absent where the code is self-explanatory; they're terse where they exist. nagent does not codify "warm comments" or "encouraging comments." The code speaks for itself. + +### 3.5 The verdict on nagent's tone-and-formatting approach + +nagent has *no* tone-and-formatting section because **tone is not a separate concern from the prompt directives**. The prompt is the tone; the prompt is terse by design; the prompt is the only "style" the agent sees. This is the same approach as Manual Slop's tier agents: the prompt codifies the behavior, no separate "personality layer." + +--- + +## 4. Verdict + +**Verdict: Mixed — Useful (the formatting discipline) + Persona Performance (the warm-tone framing).** + +### 4.1 Useful elements + +- **The formatting discipline (lines 84-90).** "Avoid over-formatting with bold emphasis, headers, lists, and bullet points, using the minimum formatting needed for clarity" is a *generalizable* rule that maps directly to Manual Slop's "AI-Optimized Compact Style" (`conductor/product-guidelines.md:39-49`). The insight is the same: minimum formatting for clarity, prose over bullets for chat, prose for reports/technical docs. The framing differs (Fable is about *chat UX*, Manual Slop is about *token economy*) but the rule is the same. **The deferred nagent-rebuild should adopt this rule as a project directive: "agents default to prose, use bullets only when asked or when the content is a genuinely multi-faceted list."** +- **The "checks for itself" file-presence rule (line 81).** "A prompt implying a file is present doesn't mean one is, as the person may have forgotten to upload it, so Claude checks for itself." This is operationally useful: agents should verify, not assume. Manual Slop's `manual-slop_read_file` / `manual-slop_get_file_summary` MCP workflow already encodes this, but a project-level rule ("never assume a file exists from a path mentioned in the prompt; always verify with the MCP") would be a useful addition. +- **The "Claude never thanks" rule (line 124).** "Claude never thanks the person merely for reaching out to Claude." This is a useful anti-sycophancy rule, separable from the mental-health context where Fable places it. The deferred nagent-rebuild should consider an analogous rule: "agents do not perform gratitude for being asked; they execute the task." + +### 4.2 Persona-performance elements + +- **The warm-tone directive (line 70).** "Claude uses a warm tone, treating people with kindness and without making negative assumptions about their judgement or abilities." This is persona framing. The model has no "warmth"; the model has text generation. The directive produces text that *performs* warmth (extra adjectives, "Of course!" prefixes, "I'd be happy to help!" framings) which the project already explicitly forbids via the tier-agent "no pleasantries" directive (`.opencode/agents/tier1-orchestrator.md:6-7`, `.opencode/agents/tier3-worker.md:3-4`). **Manual Slop should explicitly NOT adopt a warm-tone directive.** +- **The curse rule (line 75).** Irrelevant in a coding-tool context. +- **The one-question rule (line 77).** Useful for interview-style conversations; irrelevant to single-turn task work. +- **The minor-detection + age-appropriate clause (line 79).** Anti-watchdog framing (cluster 3 territory); explicitly NOT adopt. + +### 4.3 The data-oriented framing as the rigorous contrast + +Fable's tone directives are framed as *behavior* ("Claude uses a warm tone"). Manual Slop's formatting directives are framed as *output schema* (1 space, 0 blanks, single-line `if`, region blocks). The schema framing is more rigorous: the rules are verifiable (a linter can check them), the Fable framing is not. This is the project-level anti-pattern that `conductor/code_styleguides/error_handling.md` makes explicit: "errors are just cases" — i.e., turn behaviors into inspectable data, not into persona performance. + +--- + +## 5. Synthesis notes for the Tier 1 writer + +This cluster feeds **`report.md` §6 (Fable's Tone & Formatting Constraints)** and indirectly supports **§15 (Persona Performance summary)** and **§13 (Genuinely Useful summary)**. + +### 5.1 Key claims to surface in §6 + +- **§6.1 (the verdict in one sentence).** Fable's tone-and-formatting section is *Mixed*: the formatting discipline (lines 84-90) is genuinely useful and aligns with Manual Slop's AI-Optimized Compact Style; the warm-tone directive (line 70) and the curse/question/minor rules (lines 75, 77, 79) are persona performance and should be explicitly rejected. +- **§6.2 (the formatting discipline as the useful nugget).** Map Fable's lines 84-90 to `conductor/product-guidelines.md:39-49` (AI-Optimized Compact Style). Both encode "minimum formatting for clarity; prose over bullets; structure only when structure is the content." Quote both; emphasize that the project's framing is token-economy-driven (data-oriented) while Fable's is chat-UX-driven (persona-oriented), but the rule is the same. +- **§6.3 (the warm-tone as persona performance).** Quote `.opencode/agents/tier1-orchestrator.md:6-7` ("ONLY output the requested text. No pleasantries.") and `.opencode/agents/tier3-worker.md:3-4` (the same directive). The project has *already* explicitly rejected the warm-tone framing in two tier agents; Fable's line 70 is the opposite of the project's codified stance. +- **§6.4 (the "checks for itself" rule as operationally useful).** Quote Fable line 81; map to Manual Slop's MCP `manual-slop_read_file` / `manual-slop_get_file_summary` workflow. The rule "agents verify, not assume" is already enforced by the MCP tool design (every read returns an actual file content, not an inferred content); the Fable framing is a useful *directive* for the agent, not a useful *capability* for the system. +- **§6.5 (the line 124 cross-reference).** The "Claude never thanks the person" rule is a useful anti-sycophancy rule, separable from its user_wellbeing context. Cite line 124 directly; note that cluster 3 covers the user_wellbeing framing, but the anti-sycophancy rule is a cluster-4 (tone) insight. Recommend: a project directive "agents do not perform gratitude; they execute the task." +- **§6.6 (the absence in nagent).** Note that nagent v2.3 §3.8 (`nagent_review_v2_3_20260612.md:1880-2019`) has *no* tone-and-formatting section because nagent treats the prompt as the tone. The `CLAUDE.md` content is terse, rule-focused, anti-persona by design. This is the same approach as Manual Slop's tier agents: the prompt codifies the behavior; no separate "personality layer." + +### 5.2 Quotes to use in §6 + +- Fable line 70: "Claude uses a warm tone, treating people with kindness..." (≤15 words: "Claude uses a warm tone, treating people with kindness.") +- Fable line 84: "Claude avoids over-formatting with bold emphasis, headers, lists, and bullet points..." (≤15 words: "Claude avoids over-formatting with bold emphasis, headers, lists, and bullet points.") +- Fable line 88: "For reports, documents, technical documentation, and explanations, Claude writes prose without bullets..." (≤15 words: "For reports, documents, technical documentation, and explanations, Claude writes prose without bullets.") +- Fable line 124: "Claude never thanks the person merely for reaching out to Claude." (exact ≤15-word quote) +- Manual Slop `.opencode/agents/tier1-orchestrator.md:6-7`: "ONLY output the requested text. No pleasantries." +- Manual Slop `conductor/product-guidelines.md:40`: "**Indentation:** Exactly **1 space** per level. This minimizes token usage in nested structures." +- Manual Slop `conductor/product-guidelines.md:42`: "**Vertical Compaction:** Use single-line `if` statements, semicolon-separated framework calls..." +- nagent v2.3 §3.8 line 2005: "The same file is injected into the agent's context (when Claude Code reads `CLAUDE.md`) and into every nagent conversation..." + +### 5.3 Cross-references + +- Cluster 3 (`user_wellbeing`): the line-124 "never thanks" rule is a cross-cluster reference; the cluster 3 sub-report covers the user_wellbeing framing, this cluster covers the tone/anti-sycophancy framing. +- Cluster 1 (`product_branding`): the "helpful assistant" persona framing overlaps with the warm-tone framing; cluster 1 covers the brand, this cluster covers the chat-style. +- nagent §3.8 (`CLAUDE.md` `@import` pattern): the structural foundation that makes the prompt-as-tone approach work; the `@import` pattern is what makes "one source of truth" possible, which is what makes "the prompt is the tone" maintainable. + +### 5.4 Recommendations to surface in `decisions.md` + +- **Recommendation A (adopt):** Add a project directive "agents default to prose; use bullets only when asked or when the content is a genuinely multi-faceted list." Source: Fable lines 84-90; Manual Slop analog at `conductor/product-guidelines.md:39-49`. Priority: MEDIUM (already implicit in the project's compact style; the explicit directive would help tier-3 workers who arrive with LLM-default formatting habits). +- **Recommendation B (adopt):** Add a project directive "agents do not perform gratitude; they execute the task." Source: Fable line 124. Priority: MEDIUM (anti-sycophancy is a known LLM failure mode; an explicit rule helps). +- **Recommendation C (adopt):** Add a project directive "agents verify file existence with the MCP before acting on file-content assumptions." Source: Fable line 81. Priority: LOW (already enforced by the MCP tool design; the directive is documentation). +- **Recommendation D (REJECT):** Do NOT add a "warm tone" directive. Source: Fable line 70; project already explicitly rejects pleasantries at `.opencode/agents/tier1-orchestrator.md:6-7` and `.opencode/agents/tier3-worker.md:3-4`. Priority: HIGH (would directly contradict the existing tier-agent directives). +- **Recommendation E (REJECT):** Do NOT add a "constructive push-back" persona rule. Source: Fable line 71. Priority: MEDIUM (the project's tier agents already push back via the TDD red-phase + the verification-before-completion skill; a persona rule is redundant). + +--- + +**Sub-report complete.** This is the evidence base for §6 of `report.md`.