conductor(track): fable_review_20260617 cluster 9 (Computer-Use) sub-report
Tier 3 worker dispatch. Verdict: Useful + over-broad. 373 lines. Fable System Prompt.md:computer_use + file_creation_advice + producing_outputs sections cited. Project refs: guide_tools.md, edit_workflow.md, tech-stack.md. Fable artifact NOT committed.
This commit is contained in:
@@ -0,0 +1,373 @@
|
||||
# Cluster 9: Computer-Use / Skills / File Workflow
|
||||
|
||||
**Sub-agent dispatch:** Tier 3 Worker (2026-06-17). Read-only research task.
|
||||
**Sources read:**
|
||||
- `docs/artifacts/Fable System Prompt.md` lines 301-435 (`computer_use`, `skills`, `file_creation_advice`, `high_level_computer_use_explanation`, `file_handling_rules`, `producing_outputs`, `sharing_files`, `artifact_usage_criteria`, `package_management`, `examples`, `additional_skills_reminder`)
|
||||
- `docs/artifacts/Fable System Prompt.md` lines 1214-1269 (`str_replace` + `view` tool definitions; the edit protocol)
|
||||
- `docs/artifacts/Fable System Prompt.md` lines 1558-1576 (`available_skills` registry; 8 named skills)
|
||||
- `docs/artifacts/Fable System Prompt.md` lines 1586-1596 (`filesystem_configuration`; the read-only mounts)
|
||||
- `docs/guide_tools.md` lines 1-509 (MCP tools; 3-layer security; 45-tool inventory; Hook API)
|
||||
- `conductor/tech-stack.md` (file system + the "no new src/<thing>.py files" rule; centralized path resolution via `src/paths.py`)
|
||||
- `conductor/edit_workflow.md` (the edit protocol; 1-space indentation; small-edits rule; decorator-orphan pitfall; contract-change check)
|
||||
- `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` §2.4 lines 390-419 (Pattern 4 Tool Discovery; `--description` self-describing executables)
|
||||
- `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` §8.4 lines 3748-3754 (parse-then-dispatch split; the strict-parse + tolerant-dispatch pattern)
|
||||
- `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` §9 lines 3827-4115 (file splits/patches/summaries; the 4-stage pipeline; the per-language SCORE_BY_TYPE; the SHA-256 hash validation)
|
||||
- `conductor/tracks/nagent_review_20260608/decisions.md` lines 142-155 (Candidate 5: self-describing MCP tools; subsumed by `mcp_architecture_refactor_20260606`)
|
||||
- `conductor/tracks/nagent_review_20260608/decisions.md` lines 228-243 (Candidate 9: explicit `src/split_lib.py` + `src/patch_lib.py`; DEFER until needed)
|
||||
- `conductor/tracks/nagent_review_20260608/comparison_table.md` rows 11 + 12 (large files PARITY; tool discovery GAP)
|
||||
|
||||
---
|
||||
|
||||
## 1. What Fable says
|
||||
|
||||
The `computer_use` section spans lines 301-435 and is the most operationally specific part of Fable. It codifies how the model interacts with files, the filesystem, and external tools. Eleven sub-sections, each with concrete rules.
|
||||
|
||||
### 1.1 The `skills` protocol (lines 303-319)
|
||||
|
||||
Fable requires the model to read a `SKILL.md` from `/mnt/skills/` *before* creating any file, writing any code, or running any other tool. The framing is unambiguous and unconditional:
|
||||
|
||||
- **L305** (paraphrase): "Skills encode hard-won trial-and-error about producing professional output."
|
||||
- **L307** (paraphrase): "Reading the relevant SKILL.md is a required first step before writing any code, creating any file, or running any other computer tool."
|
||||
- **L309-319** (illustrative turns): Four `User` → `Claude` exchanges; in each, Claude `immediately calls view` on the relevant SKILL.md (pptx, docx, imagegen, data-analysis) before doing anything else.
|
||||
|
||||
The implicit claim: the model cannot be trusted to know the right output format from training data alone; the *environment-specific constraints* (available libraries, rendering quirks, output paths) must be re-read every session.
|
||||
|
||||
### 1.2 `file_creation_advice` (lines 321-333)
|
||||
|
||||
Fable distinguishes *file* from *inline* based on whether the artifact is standalone or conversational:
|
||||
|
||||
- **L323-329** (file-creation triggers, list of 6): "write a document/report/post/article" → .md/.html (use docx only on explicit Word-doc signal); "create a component/script/module" → code files; "fix/modify/edit my file" → edit the actual uploaded file; "make a presentation" → .pptx; "save/download" → create files; **more than 10 lines of code → create files.**
|
||||
- **L331** (the discriminator, ≤15 words): "What matters is standalone artifact vs conversational answer."
|
||||
|
||||
### 1.3 `high_level_computer_use_explanation` (lines 335-340)
|
||||
|
||||
A 4-line summary of the runtime: "Claude has a Linux computer (Ubuntu 24). Tools: bash, str_replace, create_file, view. Working directory `/home/claude` (all temp work). File system resets between tasks."
|
||||
|
||||
### 1.4 `file_handling_rules` (lines 342-351)
|
||||
|
||||
Three filesystem locations, with one *critical* rule: "USER UPLOADS ... CLAUDE'S WORK ... FINAL OUTPUTS." The model creates new files in `/home/claude` first (a scratchpad); final deliverables go to `/mnt/user-data/outputs/`. For single-file tasks <100 lines, write directly to outputs. Lines 349-351 add a per-file-type rule: decide whether computer access is actually needed based on whether the file content is already in context.
|
||||
|
||||
### 1.5 `producing_outputs` (lines 353-359)
|
||||
|
||||
The creation strategy: "SHORT (<100 lines): create the whole file in one tool call, save directly to /mnt/user-data/outputs/. LONG (>100 lines): build iteratively: outline/structure, then section by section, review, refine, copy final version." Plus the discipline rule: "REQUIRED: actually CREATE FILES when requested, not just show content, or the user can't access it."
|
||||
|
||||
### 1.6 `sharing_files` (lines 360-369)
|
||||
|
||||
A separate tool `present_files` for surfacing files to the user. Two good-example blocks: Claude calls `present_files` after generating a report or a script; *succinct, no postamble*. The framing is "share files, not folders."
|
||||
|
||||
### 1.7 `artifact_usage_criteria` (lines 371-414)
|
||||
|
||||
The longest sub-section. The artifact heuristic:
|
||||
|
||||
- **L375-382** (use artifacts for, 7 categories): "Custom code solving a specific user problem ... Any code snippet >20 lines ... Content for use outside the conversation ... Long-form creative writing ... Structured reference content ... Modifying/iterating on an existing artifact ... A standalone text-heavy document >20 lines or >1500 characters."
|
||||
- **L384-390** (do NOT use artifacts for, 6 categories): "Short code answering a question (≤20 lines) ... Short creative writing (poems, haikus, stories under 20 lines) ... Lists, tables, enumerated content, regardless of length ... Brief structured/reference content; single recipes ... Short prose; conversational inline responses ... Anything the user explicitly asked to keep short."
|
||||
|
||||
The threshold pair (20 lines / 1500 characters) is the actionable nugget.
|
||||
|
||||
### 1.8 `package_management` (lines 416-421)
|
||||
|
||||
Four operational rules: "npm: works normally ... pip: ALWAYS use `--break-system-packages` ... Virtual environments: create if needed ... Verify tool availability before use."
|
||||
|
||||
### 1.9 `examples` (lines 423-430)
|
||||
|
||||
A 5-example decision tree, each `User` → decision (view SKILL.md → file in outputs, or view content, or NO tools, or conversational response). The discriminator is *what kind of artifact* the user wants; the response shape (file vs inline) follows.
|
||||
|
||||
### 1.10 `additional_skills_reminder` (lines 432-434)
|
||||
|
||||
A load-bearing repetition: "Before creating any file, writing any code, or running any bash command, first `view` the relevant SKILL.md files. This check is unconditional: don't first decide whether the task 'needs' a skill; the skills themselves define what they cover."
|
||||
|
||||
The implicit framing: the model is **not** the authority on what counts as a relevant skill; the skills' self-descriptions are.
|
||||
|
||||
### 1.11 The available_skills registry (lines 1558-1576)
|
||||
|
||||
Eight named skills, each with a `description` field that doubles as a *trigger condition*:
|
||||
|
||||
| Skill | Trigger |
|
||||
|---|---|
|
||||
| `docx` | "any mention of 'Word doc' ... or requests to produce professional documents" |
|
||||
| `pdf` | "anytime ... the user wants to do anything with PDF files" |
|
||||
| `pptx` | "any time a .pptx file is involved in any way" |
|
||||
| `xlsx` | "any time a spreadsheet file is the primary input or output" |
|
||||
| `product-self-knowledge` | "your response would include specific facts about Anthropic's products" |
|
||||
| `frontend-design` | "distinctive, intentional visual design when building new UI" |
|
||||
| `file-reading` | "a file has been uploaded but its content is NOT in your context" |
|
||||
| `pdf-reading` | "you need to read, inspect, or extract content from PDF files" |
|
||||
| `skill-creator` | "users want to create a skill from scratch, edit, or optimize" |
|
||||
|
||||
Each is a *self-describing* prompt-template + toolset; the trigger conditions are written in natural language so the model can match them.
|
||||
|
||||
### 1.12 The tool definitions (lines 1214-1269)
|
||||
|
||||
The two edit-relevant tools:
|
||||
|
||||
- **L1216 (`str_replace`)**: "Replace a unique string in a file with another string. old_str must match the raw file content exactly and appear exactly once. ... View the file immediately before editing; after any successful str_replace, earlier view output of that file in your context is stale — re-view before further edits to the same file."
|
||||
- **L1249 (`view`)**: "Supports viewing text, images, and directory listings. ... You can optionally specify a view_range to see specific lines. ... Files with non-UTF-8 encoding will display hex escapes ... the entire file is displayed, truncating from the middle if it exceeds 16,000 characters."
|
||||
|
||||
The implicit edit protocol: read → edit → read again. Stale context is a known failure mode the model must self-correct.
|
||||
|
||||
### 1.13 The filesystem_configuration (lines 1586-1596)
|
||||
|
||||
Five read-only mounts: `/mnt/user-data/uploads`, `/mnt/transcripts`, `/mnt/skills/public`, `/mnt/skills/private`, `/mnt/skills/examples`. The rule: "Do not attempt to edit, create, or delete files in these directories. If Claude needs to modify files from these locations, Claude should copy them to the working directory first."
|
||||
|
||||
The implicit framing: read-only is the *default*; writeable is the *exception*. Copy-then-edit is the unblock path.
|
||||
|
||||
### 1.14 The aggregation
|
||||
|
||||
Fable's `computer_use` section is operationally dense and load-bearing. It is *not* persona framing; it is a concrete protocol with explicit thresholds (20 lines, 1500 chars, <100 lines = one-shot, >100 lines = iterative), explicit rules (copy-then-edit, read-before-edit, no postamble), and explicit tools (bash, str_replace, create_file, view, present_files, search_mcp_registry, suggest_connectors). The 8 named skills are a *registry* that auto-extends — adding a skill is adding a description field, not editing a dispatcher.
|
||||
|
||||
The two non-trivial claims:
|
||||
1. **The model cannot be trusted to know the right output format from training data alone.** The skill-read protocol is the operational consequence.
|
||||
2. **Read-before-edit is non-negotiable; stale context is the most common failure mode.** The str_replace description (L1216) is the explicit discipline rule.
|
||||
|
||||
Both are *useful*; both are also what the project's `edit_workflow.md` codifies at the agent-system level. The §4 verdict evaluates them in that context.
|
||||
|
||||
---
|
||||
|
||||
## 2. What this project does
|
||||
|
||||
Manual Slop's file workflow is implemented in three layers: a *security layer* (the 3-layer allowlist), a *tool layer* (the 45 MCP tools), and a *discipline layer* (the edit workflow). Each layer overlaps with a Fable rule but codifies it differently.
|
||||
|
||||
### 2.1 The 3-layer filesystem security (guide_tools.md:7-53)
|
||||
|
||||
`docs/guide_tools.md:7-53` documents `_resolve_and_check(path)` as the gate every filesystem-touching tool passes through. Three layers:
|
||||
|
||||
- **Layer 1 (Allowlist Construction, `configure`)**: resets `_allowed_paths` and `_base_dirs` on every call; sets `_primary_base_dir` from `extra_base_dirs[0]` (resolved) or `Path.cwd()`; iterates `file_items` (from `aggregate.build_file_items()`) and resolves each path to absolute; adds the file to `_allowed_paths`, the parent directory to `_base_dirs`. The allowlist is *per-send*, not global.
|
||||
- **Layer 2 (Path Validation, `_is_allowed`)**: blacklist first (`history.toml` or `*_history.toml` → deny; prevents AI from reading conversation history); explicit allowlist (`_allowed_paths`); CWD fallback (if `_base_dirs` empty, any path under `cwd()` allowed); base-directory containment (`relative_to()`); default deny.
|
||||
- **Layer 3 (Resolution Gate, `_resolve_and_check`)**: convert raw path to `Path`; resolve to absolute; call `_is_allowed()`; return `(resolved_path, "")` or `(None, error_message)` with the full list of allowed base directories for debugging.
|
||||
|
||||
The hardening: paths are resolved (symlinks followed) before comparison, preventing symlink traversal. The blacklist for `history.toml` is the project's analog to Fable's read-only mounts — *the model is denied access to specific paths by category, not by exception*.
|
||||
|
||||
The project's version is **stricter** than Fable's: Fable's read-only mounts are advisory (the rule is "don't attempt to edit; copy first"); Manual Slop's allowlist is **enforced** at the tool dispatch layer. The model cannot bypass it without writing to a non-allowlisted path, which fails the dispatch.
|
||||
|
||||
### 2.2 The 45 MCP tools (guide_tools.md:55-196)
|
||||
|
||||
`docs/guide_tools.md:55-196` enumerates the 45 tools in `dispatch` (a flat if/elif chain at `mcp_client.py:1322`). The categories:
|
||||
|
||||
- **File I/O (7 tools)**: `read_file`, `list_directory`, `search_files`, `get_file_slice`, `set_file_slice`, `edit_file`, `get_tree`. Note `set_file_slice` and `edit_file` are the surgical-edit primitives; `set_file_slice` is "literal line replacement by design" per `conductor/edit_workflow.md:78-89`.
|
||||
- **AST-Based Python (15 tools)**: `py_get_skeleton`, `py_get_code_outline`, `py_get_definition`, `py_update_definition`, `py_get_signature`, `py_set_signature`, `py_get_class_summary`, `py_get_var_declaration`, `py_set_var_declaration`, `py_find_usages`, `py_get_imports`, `py_check_syntax`, `py_get_hierarchy`, `py_get_docstring`, `py_remove_def`, `py_add_def`, `py_move_def`, `py_region_wrap`. (Note: guide_tools.md lists 18 here, not 15. The 18 are an enumeration including structural mutators.)
|
||||
- **C/C++ AST (10 tools)**: `ts_c_get_skeleton`, `ts_cpp_get_skeleton`, `ts_c_get_code_outline`, `ts_cpp_get_code_outline`, `ts_c_get_definition`, `ts_cpp_get_definition`, `ts_c_update_definition`, `ts_cpp_update_definition`, `ts_c_get_signature`, `ts_cpp_get_signature`.
|
||||
- **Analysis (3 tools)**: `get_file_summary`, `get_git_diff`, `derive_code_path`.
|
||||
- **Network (2 tools)**: `web_search` (DuckDuckGo HTML scrape), `fetch_url`.
|
||||
- **Runtime (1 tool)**: `get_ui_performance` (no filesystem access).
|
||||
- **Beads (4 tools)**: `bd_list`, `bd_create`, `bd_update`, `bd_ready`.
|
||||
|
||||
The model *cannot* run arbitrary bash or write arbitrary files — `run_powershell` is the only shell tool, and it requires HITL confirmation via the `ShellRunner` (see guide_tools.md:475-509 and `conductor/tech-stack.md`).
|
||||
|
||||
### 2.3 The edit_workflow protocol (conductor/edit_workflow.md)
|
||||
|
||||
The project's edit discipline is codified at the agent-system level, not the model level. Five load-bearing rules:
|
||||
|
||||
- **§2 "Verify Before Editing"** (lines 14-24): "DO NOT use `git checkout` or `git restore` to 'revert' your way to a clean state." The discipline rule: run `py_check_syntax` + `get_file_slice` on the exact lines before any edit.
|
||||
- **§3 "Reading Before Editing (CRITICAL)"** (lines 26-31): "Use `get_file_slice` to get the EXACT text including all whitespace and EOL. Copy text directly from the tool output — do NOT reformat."
|
||||
- **§6 "The Decorator-Orphan Pitfall"** (lines 51-68): a specific failure mode where `@property` is orphaned onto a new method if the anchor is wrong. The rule: anchor on a non-decorated landmark, or include the decorator in the replacement.
|
||||
- **§7 "ast.parse() Is Not Enough"** (lines 70-76): semantic errors (wrong decorator targets, missing `self`) are not caught by `py_check_syntax`. The discipline: after any multi-line edit, import the module, instantiate the class, call the new method.
|
||||
- **§8 "set_file_slice IS Valid for Multi-Line Content"** (lines 78-108): the contract-change check is mandatory for any edit that changes a public interface (signature, return type, yield shape, class hierarchy, public attribute name). Use `py_find_usages` to locate callers before changing a contract; update ALL callers in the same atomic commit.
|
||||
|
||||
The protocol is **stricter than Fable's**. Fable's rule (L1216: "View the file immediately before editing") is *one* rule among many; Manual Slop's protocol is *eight* numbered rules with named failure modes (decorator-orphan, ast.parse-not-enough, contract-change-check).
|
||||
|
||||
### 2.4 The file-naming convention (AGENTS.md "File Size and Naming Convention")
|
||||
|
||||
The project's anti-filesplittism stance is explicit: "Large files are FINE." `AGENTS.md` (the project's root agent-facing file) rules: "Helpers and sub-systems go in the parent module. E.g., AI-client-specific helpers go in `src/ai_client.py`; MCP-client code goes in `src/mcp_client.py`."
|
||||
|
||||
The consequence: there is no Fable-style `skills/` directory with `SKILL.md` per format. The format-specific knowledge is in the project's source code (the `tree_sitter` bindings in `file_cache.py`; the `mcp_client.py` tool implementations; the `pyproject.toml` dependency declarations).
|
||||
|
||||
### 2.5 The path resolution (conductor/tech-stack.md, `src/paths.py`)
|
||||
|
||||
`conductor/tech-stack.md` documents `src/paths.py` as "Centralized module for path resolution. Supports project-specific conductor directory overrides via project TOML (`[conductor].dir`)." Plus "Path Resolution Metadata" exposing the source of each resolved path (default, env var, config file) for GUI display, and "Runtime Re-Resolution" via `reset_resolved()`.
|
||||
|
||||
The project's analog to Fable's `filesystem_configuration`: *paths are declared once, in the centralized config; the model never invents paths.* The `paths.py` module is the single source of truth; the model sees the resolved paths via `_pending_gui_tasks`, not by navigating the filesystem.
|
||||
|
||||
### 2.6 The aggregation
|
||||
|
||||
Manual Slop's file workflow is **enforced, not prompted**. The 3-layer allowlist is enforced at dispatch; the edit_workflow rules are enforced at the agent-system level; the path resolution is enforced at the config layer. The model has *less* freedom than Fable's model (no arbitrary bash, no arbitrary writes, no `present_files` tool, no `search_mcp_registry`), but *more* rigor (symlink-resolved paths, SHA-style content checks via mtime, AST-aware edit tools, contract-change check).
|
||||
|
||||
The project's analog to Fable's `available_skills` is *the 45-tool inventory itself*. Each tool's description field IS a trigger condition (e.g., `py_get_skeleton`: "Signatures + docstrings, bodies replaced with `...`. Uses tree-sitter."); the model reads the tool inventory once at startup and matches tool-to-task. But the inventory is hard-coded, not extensible — adding a tool requires edits in `dispatch()` (per `nagent_review_v2_3_20260612.md:417-419`: "Adding a tool requires: 1. Edit dispatch() to add the branch; 2. Update the security allowlist in `_resolve_and_check` (if filesystem access); 3. Update capability declaration; 4. Add tests").
|
||||
|
||||
---
|
||||
|
||||
## 3. What nagent does
|
||||
|
||||
nagent's file workflow is documented across §2.4 (Pattern 4 Tool Discovery), §8.4 (parse-then-dispatch split), and §9 (file splits/patches/summaries). The three sections address three distinct aspects of "computer use": tool discovery, error handling, and large-file handling.
|
||||
|
||||
### 3.1 Pattern 4: Tool Discovery via `--description` (nagent_review_v2_3_20260612.md:390-419 + decision candidate 5)
|
||||
|
||||
The `--description` self-describing executable pattern is the structural alternative to Fable's `available_skills` and to Manual Slop's hard-coded `dispatch`:
|
||||
|
||||
- **nagent's mechanism** (per `nagent_review_v2_3_20260612.md:390-419`): each `bin/nagent-*` executable starts with `exit_on_description(NAGENT_*_DESCRIPTION)` (a one-liner that prints the tool's description and exits 0 if `--description` is in `sys.argv`). At startup, the main loop calls `collect_bin_tool_descriptions(bin_dir)` which iterates every executable in `bin/`, runs `--description`, parses stdout, and concatenates the descriptions into the startup prompt.
|
||||
- **The 9 nagent tools** (per `nagent_review_v2_3_20260612.md:402-414`): `nagent` (main loop), `nagent-llm-text`, `nagent-llm-upload`, `nagent-file-edit`, `nagent-file-split`, `nagent-file-patch`, `nagent-file-summarize`, `nagent-gc`. Each is a thin wrapper; the real logic lives in `bin/helpers/*_lib.py`.
|
||||
- **The "no central registry" claim** (`nagent_review_v2_3_20260612.md:1925-1932`): "There is no central registry: `collect_bin_tool_descriptions()` discovers tools by running every `bin/` executable with `--description` and injecting the results into the startup prompt. A new tool becomes visible to the loop simply by being an executable in `bin/` that handles `--description`."
|
||||
|
||||
The pattern's verdict (per `comparison_table.md:31` and `decisions.md:142-155`): **GAP (Application)**. nagent's pattern is genuinely better for extensibility; Manual Slop's `dispatch` if/elif chain is fine but not extensible. The fix is subsumed by `mcp_architecture_refactor_20260606` (the sub-MCP extraction would naturally produce self-describing modules).
|
||||
|
||||
### 3.2 §8.4: The parse-then-dispatch split (nagent_review_v2_3_20260612.md:3748-3754)
|
||||
|
||||
The cross-cutting pattern that *also* applies to Fable's edit tools:
|
||||
|
||||
- **The separation**: `parse_response` (uses `nagent_tags.py:parse_tag_document`) is *strict* (rejects unknown tags, malformed attributes, unterminated bodies); `process_tags` (the dispatcher) is *tolerant* (errors are data; the LLM sees them and responds).
|
||||
- **The generalization**: "validate at the boundary, handle errors as data inside. The same pattern is in Manual Slop's `data_oriented_error_handling_20260606` (`Result[T, ErrorInfo]` envelope)."
|
||||
|
||||
The application to Fable's `str_replace` and `view` tools: the Fable description (L1216) instructs the model to *self-validate* by re-viewing after editing ("after any successful str_replace, earlier view output of that file in your context is stale"). Manual Slop's `set_file_slice` and `edit_file` *enforce* the validation at the tool layer (the tool re-reads the file before writing; the result includes the new file content for the model to verify). nagent's `validate_index` (in `bin/helpers/nagent_file_patch_lib.py`) is the strongest: SHA-256 hash validation that rejects patches against a stale source.
|
||||
|
||||
### 3.3 §9: The 4-stage file pipeline (nagent_review_v2_3_20260612.md:3827-4115)
|
||||
|
||||
The large-file handling is the deep-dive. The pipeline is *data-oriented*:
|
||||
|
||||
1. **Inline read** (file < 64KB): read the whole file; pass to LLM.
|
||||
2. **Split** (file > 64KB): `nagent-file-split <file> --output /tmp/split --target-bytes 32768 --natural`. The splitter uses *per-language `SCORE_BY_TYPE`* (regex + line counts + brace/JSON/XML depth, no tree-sitter) and writes `index.json` with `source_path`, `source_sha256`, `source_size_bytes`, `source_line_count`, `split_type`, `target_bytes`, `segments[]`.
|
||||
3. **Edit segments**: the user or LLM edits the per-segment files.
|
||||
4. **Patch**: `nagent-file-patch <index>` calls `validate_index(index, require_hash_match=True)`; if the source SHA-256 doesn't match `index.source_sha256`, the patch is rejected (unless `--force`). The patch operation merges segments, makes a unified diff, optionally writes back.
|
||||
|
||||
The 12 supported languages (`nagent_review_v2_3_20260612.md:3894-3909`): `txt`, `md`, `cpp`, `py`, `xml`, `js`, `ts`, `json`, `yaml`, `go`, `rs`, `java`. Each has its own `SCORE_BY_TYPE` (the splitter heuristic). The default target size is 32KB.
|
||||
|
||||
The Manual Slop equivalent (`comparison_table.md:30` + `report.md:331-376`):
|
||||
|
||||
| nagent | Manual Slop |
|
||||
|---|---|
|
||||
| `nagent-file-split` with per-language `SCORE_BY_TYPE` (no tree-sitter) | `aggregate.py:build_file_items()` + `py_get_skeleton` + `ts_c_*_get_skeleton` (tree-sitter) |
|
||||
| `index.json` with `source_sha256`, `segments[]` | No explicit `index.json`; implicit in `_reread_file_items` (mtime-based, not hash-based) |
|
||||
| `nagent-file-patch` with strict `validate_index` (SHA-256 hash check) | `set_file_slice` / `edit_file` with re-read + string-match (no SHA-256) |
|
||||
| `nagent-file-summarize` cascades to `nagent-file-split --summarize` for > 64 KB | `RAGEngine._chunk_code` cascades to chunking (mtime-based, ChromaDB) |
|
||||
|
||||
Verdict (`comparison_table.md:30` + `report.md:373`): **PARITY (DIFFERENT MECHANISM)**. Both have the "split / patch / summarize as explicit data artifacts" insight. nagent uses subprocesses + per-language scoring + hash validation; Manual Slop uses tree-sitter + in-process + mtime validation. The crucial difference: Manual Slop's tree-sitter is more accurate but slower; nagent's natural-splitter is faster but less accurate.
|
||||
|
||||
The Manual Slop recommendation (`nagent_review_v2_3_20260612.md:4104-4108`): "Don't add the natural-splitter fallback yet. Manual Slop's tree-sitter covers 95% of real workloads. ... Adopt it only if a 200KB+ file scenario actually surfaces." This is Decision Candidate 9 (per `decisions.md:228-243`): **DEFER UNTIL NEEDED**.
|
||||
|
||||
### 3.4 The aggregation
|
||||
|
||||
nagent's file workflow is **data-shaped, not prompt-shaped**. The tools are self-describing (no central registry); the splits are explicit (`index.json` with hash validation); the patches are unified diffs; the errors are data (`status="error"` in result wrappers, per `nagent_review_v2_3_20260612.md:3758-3765`).
|
||||
|
||||
The 3 layers of nagent's design that map to Manual Slop's gaps:
|
||||
1. **Tool discovery**: GAP. Manual Slop's `dispatch` if/elif chain is fine but not extensible. Subsumed by `mcp_architecture_refactor_20260606`.
|
||||
2. **Parse-then-dispatch**: PARITY. Manual Slop's `Result[T, ErrorInfo]` envelope (per `data_oriented_error_handling_20260606`) is the same idea applied at the function-call layer.
|
||||
3. **Large-file pipeline**: PARITY (DIFFERENT MECHANISM). Both have the insight; nagent uses subprocesses + hash validation; Manual Slop uses tree-sitter + mtime. The hash-validation gap is real but small (mtime is sufficient for the typical use case).
|
||||
|
||||
---
|
||||
|
||||
## 4. Verdict
|
||||
|
||||
**Useful + over-broad.** Fable's `computer_use` section + the `file_creation_advice` + the `producing_outputs` + the `available_skills` registry has genuinely useful elements but is over-broad for Manual Slop's per-developer, scripted workflow. The MCP-based tooling in Manual Slop is the more constrained, auditable alternative.
|
||||
|
||||
### 4.1 The useful elements (preserve in the rebuild)
|
||||
|
||||
1. **The file-presence check** (Fable L81 + L1216): "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 real operational discipline — agents must verify, not assume. Manual Slop's `manual-slop_read_file` / `manual-slop_get_file_summary` workflow codifies the same discipline at the tool layer. The cluster 4 sub-report (L48-51) flags this as the "useful nugget" of cluster 4; the same discipline re-appears here.
|
||||
|
||||
2. **The format-based triggers** (Fable L323-329): the 6-line table mapping user signal to file format. The discriminator (L331: "standalone artifact vs conversational answer") is a useful heuristic that doesn't appear in Manual Slop's directives. The 20-line / 1500-char artifact threshold (L382) is an actionable rule. The rebuild should consider codifying these in `conductor/product-guidelines.md` (under "AI-Optimized Compact Style") or a new `conductor/code_styleguides/output_format_decision.md`.
|
||||
|
||||
3. **The "do not include boilerplate" rule** (Fable L396): "Conversational responses (web search results, research summaries, analysis) should NOT use report-style headers and structure; follow tone_and_formatting: natural prose, minimal headers, concise." This is the same insight as Manual Slop's "natural prose for typical conversation" rule (cluster 4 sub-report, L56-58). Fable's framing is more concrete (it explicitly identifies web-search and research-summary as the cases where boilerplate creeps in).
|
||||
|
||||
4. **The read-before-edit discipline** (Fable L1216): "View the file immediately before editing; after any successful str_replace, earlier view output of that file in your context is stale — re-view before further edits to the same file." This maps directly to Manual Slop's `conductor/edit_workflow.md:26-31` ("Reading Before Editing (CRITICAL)"). The Fable rule is the model's self-discipline; Manual Slop's is enforced at the agent-system level via `get_file_slice` + `set_file_slice` (the tool re-reads the file before writing). Manual Slop's enforcement is stronger.
|
||||
|
||||
5. **The "unconditional" framing for skills** (Fable L432-434): "Before creating any file, writing any code, or running any bash command, first `view` the relevant SKILL.md files. This check is unconditional." This is a useful *style* for directives — don't make the agent decide whether a rule applies; the rule applies. The Manual Slop analog is `conductor/workflow.md` §"Skip-Marker Policy" ("When the underlying issue is fixable in-session, FIX IT INSTEAD of adding a skip marker"). Both reject agent judgment in favor of rule application.
|
||||
|
||||
### 4.2 The over-broad elements (reject or de-prioritize in the rebuild)
|
||||
|
||||
1. **The 8 named skills (L1558-1576)** are product features for a chat UI serving many users with diverse output needs (Word, PowerPoint, Excel, PDF generation). Manual Slop is a coding tool for one developer; the formats are `.py`, `.toml`, `.md`, and `.json`. The 8-skill registry is over-engineered. The Manual Slop analog is the 45-tool inventory (which is itself over-broad for the typical task but justified by the codebase's breadth — Python + C/C++ + Markdown + RAG + Beads). The cluster 10 sub-report (MCP App Suggestions) addresses a related concern.
|
||||
|
||||
2. **The `/mnt/user-data/uploads` vs `/home/claude` vs `/mnt/user-data/outputs` separation** (Fable L342-351) is a *chat-UI* artifact: the user uploads files; the model works on them; the model produces outputs; the user downloads outputs. Manual Slop has no equivalent separation because there is no "upload" — the model reads files from the project tree, edits them, and the project tree is the output. The 3-layer allowlist (guide_tools.md:7-53) is the right abstraction for Manual Slop's domain; Fable's filesystem_configuration is the right abstraction for Fable's domain.
|
||||
|
||||
3. **The `present_files` tool** (Fable L362-369): "Share files, not folders. No long post-ambles after linking." This is a chat-UI tool that doesn't apply to Manual Slop. The Manual Slop analog is the Hook API (`docs/guide_tools.md:304-333`) which exposes the GUI state to external automation — a different mechanism for a different purpose.
|
||||
|
||||
4. **The `search_mcp_registry` + `suggest_connectors` tools** (Fable L1199-1244): "Call this when connecting to a new MCP might help resolve the user query." This is a *connector-discovery* mechanism for an open ecosystem. Manual Slop's MCP tools are internal and curated (45 tools, all in `mcp_client.py`); there is no registry to search. The `ExternalMCPManager` (per `conductor/tech-stack.md`) provides a similar capability for *external* MCP servers, but it's opt-in, not auto-triggered. Cluster 10 covers this in more detail.
|
||||
|
||||
5. **The `package_management` rules** (Fable L416-421): "pip: ALWAYS use `--break-system-packages`." This is Fable-environment-specific (Ubuntu 24 in a container with no externally-managed Python environment). Manual Slop uses `uv` (per `conductor/tech-stack.md`: "uv: An extremely fast Python package and project manager") which manages the Python environment in `pyproject.toml` + `.venv`. The pip rule is irrelevant; the uv workflow is the project's analog.
|
||||
|
||||
### 4.3 The nagent alternative (the structural fix)
|
||||
|
||||
The `--description` self-describing pattern (nagent §2.4 / decision candidate 5) is the structural alternative to both Fable's `available_skills` registry and Manual Slop's hard-coded `dispatch`. If the rebuild wants to make the tool inventory *extensible* without editing `dispatch()`, the fix is:
|
||||
|
||||
1. Each tool (or each sub-MCP module, per `mcp_architecture_refactor_20260606`) emits a `--description` block on `--help`.
|
||||
2. The `dispatch` function introspects via `mcp_client.get_tool_schemas()` and includes the descriptions in the AI's initial context automatically.
|
||||
3. Adding a tool = dropping a file with a description; no `dispatch()` edit; no allowlist edit; no capability-declaration edit.
|
||||
|
||||
This is a real gap (per `comparison_table.md:31` and `decisions.md:142-155`); the rebuild's `mcp_architecture_refactor_20260606` track is the right scope. The `--description` pattern is *not* Fable's `available_skills` (Fable's pattern is in-prompt self-description; nagent's is executable-level self-description), but the spirit is the same: tools describe themselves; the dispatcher is data-driven.
|
||||
|
||||
### 4.4 What the rebuild should adopt
|
||||
|
||||
| Fable pattern | Adopt? | Manual Slop equivalent / next step |
|
||||
|---|---|---|
|
||||
| File-presence check (L81) | **Yes, already adopted** | `manual-slop_read_file` / `manual-slop_get_file_summary` workflow |
|
||||
| Read-before-edit (L1216) | **Yes, already adopted** | `conductor/edit_workflow.md` §3 (enforced via `get_file_slice` + `set_file_slice`) |
|
||||
| Format-based triggers (L323-329) | **Yes, codify** | Add to `conductor/product-guidelines.md` or new `output_format_decision.md` |
|
||||
| 20-line / 1500-char artifact threshold (L382) | **Yes, codify** | Same location as above |
|
||||
| "Unconditional" framing for rules (L432-434) | **Yes, adopt** | Already partial via `conductor/workflow.md` Skip-Marker Policy |
|
||||
| 8 named skills (L1558-1576) | **No** | Over-engineered for one-developer scope |
|
||||
| 3-location filesystem (L342-351) | **No** | Manual Slop has no upload/output separation |
|
||||
| `present_files` tool (L362-369) | **No** | Chat-UI specific; Hook API is the project's analog |
|
||||
| `search_mcp_registry` (L1199-1244) | **No** | Manual Slop has no open ecosystem |
|
||||
| pip `--break-system-packages` (L419) | **No** | Manual Slop uses `uv` |
|
||||
| `--description` self-describing pattern (nagent §2.4) | **Yes, deferred to mcp_architecture_refactor** | Subsumed by `mcp_architecture_refactor_20260606` |
|
||||
| SHA-256 hash validation for edits (nagent §9.4) | **Yes, partial adoption** | Replace mtime validation with hash for stronger guarantees; subsumed by Candidate 9 (defer until need) |
|
||||
|
||||
---
|
||||
|
||||
## 5. Synthesis notes for the Tier 1 writer
|
||||
|
||||
This cluster feeds `report.md` §11 ("Fable's Computer-Use / File Workflow") directly. Cross-references to §13 ("Genuinely Useful Patterns"), §14 ("Anti-User Watchdog Patterns"), §15 ("Persona Performance Patterns").
|
||||
|
||||
### 5.1 Key claims to surface in §11
|
||||
|
||||
1. **The file-presence check (Fable L81) and the read-before-edit rule (Fable L1216) are the genuinely useful nuggets.** Both are already codified in Manual Slop via `manual-slop_read_file` + `conductor/edit_workflow.md:26-31`. Manual Slop's enforcement is *stronger* than Fable's (the tool re-reads the file before writing; Fable's rule is model-self-discipline).
|
||||
|
||||
2. **The format-based triggers (Fable L323-329) and the 20-line / 1500-char artifact threshold (Fable L382) are concrete and codifiable.** They don't appear in Manual Slop's current directives. Add to `conductor/product-guidelines.md` (under "AI-Optimized Compact Style") or create a new `conductor/code_styleguides/output_format_decision.md`. The decision discriminator (L331: "standalone artifact vs conversational answer") is the actionable insight.
|
||||
|
||||
3. **The 8 named skills (Fable L1558-1576) are over-engineered for Manual Slop's scope.** Manual Slop is a coding tool for one developer; the formats are Python + TOML + Markdown + JSON. The 45-tool inventory is itself broad but justified by the codebase's breadth (Python + C/C++ + RAG + Beads + network). The 8-skill registry is a chat-UI product feature, not a coding-tool feature.
|
||||
|
||||
4. **The 3-location filesystem (Fable L342-351) is irrelevant to Manual Slop.** The project has no upload/output separation; the 3-layer allowlist (`guide_tools.md:7-53`) is the right abstraction. Reject the chat-UI framing.
|
||||
|
||||
5. **The `package_management` rules (Fable L416-421) are environment-specific and irrelevant.** Manual Slop uses `uv` (per `conductor/tech-stack.md`); the pip `--break-system-packages` rule is a chat-UI container quirk.
|
||||
|
||||
6. **The nagent `--description` self-describing pattern (nagent §2.4) is the structural alternative to both Fable's `available_skills` and Manual Slop's hard-coded `dispatch`.** This is a real gap (per `comparison_table.md:31`); the rebuild's `mcp_architecture_refactor_20260606` track is the right scope.
|
||||
|
||||
7. **The nagent SHA-256 hash validation (nagent §9.4) is a stronger guarantee than Manual Slop's mtime validation.** Decision Candidate 9 (per `decisions.md:228-243`) is DEFER UNTIL NEEDED. Document the nagent pattern as a reference; don't adopt until a 200KB+ file scenario surfaces.
|
||||
|
||||
8. **The `present_files` tool (Fable L362-369) and the `search_mcp_registry` + `suggest_connectors` tools (Fable L1199-1244) are chat-UI-specific.** Reject in the rebuild. Manual Slop's Hook API (`guide_tools.md:304-333`) and ExternalMCPManager are the project analogs.
|
||||
|
||||
### 5.2 Quotes to use in §11
|
||||
|
||||
- **Fable L81** (file-presence): "Claude checks for itself" (the full sentence: "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"). ≤15 words: "the model should check for the file's presence."
|
||||
- **Fable L307** (skill-read mandatory): "Reading the relevant SKILL.md is a required first step before writing any code." ≤15 words.
|
||||
- **Fable L331** (format discriminator): "What matters is standalone artifact vs conversational answer." ≤15 words.
|
||||
- **Fable L382** (artifact threshold): "A standalone text-heavy document >20 lines or >1500 characters." ≤15 words.
|
||||
- **Fable L1216** (read-before-edit): "View the file immediately before editing; after any successful str_replace, earlier view output of that file in your context is stale." (paraphrase; full exceeds 15 words)
|
||||
- **Fable L1595** (read-only enforcement): "Do not attempt to edit, create, or delete files in these directories." ≤15 words.
|
||||
- **`guide_tools.md:33-37`** (3-layer security): "Blacklist (hard deny): If filename is `history.toml` or ends with `_history.toml`, return `False`. ... Explicit allowlist: If resolved path is in `_allowed_paths`, return `True`. ... Default deny: All other paths are rejected."
|
||||
- **`conductor/edit_workflow.md:78-79`** (the protocol discipline): "`set_file_slice` IS Valid for Multi-Line Content (Revised 2026-06-09) ... The previous rule ('Do not use set_file_slice for multi-line content') was wrong. `set_file_slice` does literal line replacement by design and is the right tool for 3-10 line surgical edits."
|
||||
- **`conductor/edit_workflow.md:106-108`** (the contract-change check): "If you change a contract and don't update callers, you have broken the codebase."
|
||||
- **`nagent_review_v2_3_20260612.md:1925-1927`** (the no-central-registry claim): "There is no central registry: `collect_bin_tool_descriptions()` discovers tools by running every `bin/` executable with `--description` and injecting the results into the startup prompt."
|
||||
- **`nagent_review_v2_3_20260612.md:3990-3995`** (the safety property): "The patch operation validates the source hasn't changed. If the source has been modified since the split, the patch is rejected (unless `--force`)."
|
||||
- **`nagent_review_v2_3_20260612.md:4104-4108`** (the Manual Slop recommendation): "Don't add the natural-splitter fallback yet. Manual Slop's tree-sitter covers 95% of real workloads. ... Adopt it only if a 200KB+ file scenario actually surfaces."
|
||||
- **`decisions.md:144-146`** (Candidate 5, the self-describing pattern): "Manual Slop's 45 MCP tools are dispatched by a flat if/elif in `mcp_client.py:dispatch`. Adding a tool requires edits in 4 places (dispatch, security allowlist, capability declaration, tests). nagent's `--description` self-describing executable pattern is more extensible: drop an executable, it auto-appears."
|
||||
- **`decisions.md:243`** (Candidate 9, the DEFER): "Recommended priority. DEFER UNTIL NEEDED. No current 1:1 use case requires explicit split/patch. If a future file is genuinely too large for tree-sitter to handle inline, this becomes Candidate #2-priority."
|
||||
|
||||
### 5.3 The §13 / §14 / §15 cross-references
|
||||
|
||||
- **§13 ("Genuinely Useful Patterns").** Cite the file-presence check (Fable L81), the format-based triggers (Fable L323-329), the 20-line / 1500-char threshold (Fable L382), and the read-before-edit discipline (Fable L1216). Each maps to a Manual Slop analog that is *more rigorous* than Fable's framing. Cite `guide_tools.md:7-53` (3-layer security) and `conductor/edit_workflow.md:1-209` (the 8 numbered rules) as the Manual Slop implementations.
|
||||
|
||||
- **§14 ("Anti-User Watchdog Patterns").** Fable's `present_files` tool (L362-369) and the `search_mcp_registry` + `suggest_connectors` tools (L1199-1244) are not strictly anti-user, but they are chat-UI product features that don't fit Manual Slop's domain. Cite these as "not applicable" rather than anti-user. The `recommended_claude_apps` tool (Fable L1180-1197) is mildly anti-user (it nudges the user toward Anthropic products); reject in the rebuild.
|
||||
|
||||
- **§15 ("Persona Performance Patterns").** Fable's `present_files` framing ("succinct, no post-ambles" per L362-369) is *style discipline*, not persona; the framing is too narrow to be persona. The genuinely persona-shaped claim is Fable's "high-fidelity, professional output" framing throughout the `computer_use` section — the model is positioned as a *professional assistant*, not a *transformation function over data*. Manual Slop's analog (the data-oriented error handling convention per `conductor/code_styleguides/error_handling.md`) rejects the professional-assistant framing in favor of the transformation-function framing. Cite Fable's framing in §15; reject explicitly.
|
||||
|
||||
### 5.4 The non-obvious connection to the data-oriented error handling convention
|
||||
|
||||
Cluster 9 has a sibling connection to the data-oriented error handling convention (per `conductor/code_styleguides/error_handling.md`) that cluster 5 (mistakes) flagged. The connection:
|
||||
|
||||
- **Fable's `str_replace` description (L1216)** instructs the model to *self-validate* by re-viewing after editing ("stale context" is the failure mode).
|
||||
- **Manual Slop's `set_file_slice` and `edit_file`** *enforce* the validation at the tool layer (the tool re-reads the file before writing; the result includes the new file content for the model to verify).
|
||||
- **nagent's `validate_index` (per `nagent_review_v2_3_20260612.md:3996-4006`)** is the strongest: SHA-256 hash validation that *rejects* patches against a stale source.
|
||||
|
||||
The three implementations form a progression: prompt-level discipline (Fable, weak) → tool-level discipline (Manual Slop, medium) → data-level discipline (nagent, strong). The data-level discipline is the data-oriented error handling convention applied to the file-write boundary. The synthesis report should surface this parallel in §11.
|
||||
|
||||
### 5.5 What the §11 verdict should be
|
||||
|
||||
**Verdict: Useful + over-broad.** The file-presence check, the format-based triggers, the 20-line / 1500-char threshold, and the read-before-edit discipline are genuinely useful and worth codifying in Manual Slop's directives. The 8 named skills, the 3-location filesystem, the `present_files` tool, and the `package_management` rules are over-engineered for Manual Slop's per-developer, scripted workflow and should be rejected. The `search_mcp_registry` + `suggest_connectors` tools are chat-UI product features that don't fit the project's domain.
|
||||
|
||||
**The recommended Manual Slop action:**
|
||||
1. Keep the existing 3-layer allowlist (`guide_tools.md:7-53`) and `conductor/edit_workflow.md` protocol as-is. They are *more rigorous* than Fable's framing.
|
||||
2. Add the format-based triggers (Fable L323-329) and the 20-line / 1500-char artifact threshold (Fable L382) to `conductor/product-guidelines.md` (under "AI-Optimized Compact Style") or create a new `conductor/code_styleguides/output_format_decision.md`.
|
||||
3. Explicitly reject the 8 named skills, the 3-location filesystem, the `present_files` tool, the `search_mcp_registry` + `suggest_connectors` tools, and the pip `--break-system-packages` rule as chat-UI-specific patterns that don't apply to Manual Slop's domain.
|
||||
4. Flag the nagent `--description` self-describing pattern (nagent §2.4) as a deferred-rebuild candidate, subsumed by `mcp_architecture_refactor_20260606` (per `decisions.md:142-155`).
|
||||
5. Flag the nagent SHA-256 hash validation (nagent §9.4) as a deferred candidate, subsumed by Decision Candidate 9 (DEFER UNTIL NEEDED per `decisions.md:228-243`).
|
||||
|
||||
---
|
||||
|
||||
**Sub-report complete.** This is the evidence base for §11 of `report.md`.
|
||||
Reference in New Issue
Block a user