Ornith best practices: harness-neutral wording

Model-Best-Practices/Ornith-q8-best-practices.md

@@ -1,6 +1,6 @@
 # Ornith Q8 best practices
 
-How to get real work out of Ornith 1.5-9B (Qwen3.5-based, 8-bit / Bfp8) on one Tenstorrent p150 through Pantheon + Argus. From the 2026-10-25 runs (social-media doc, K80 MTP Phase 1).
+How to get real work out of Ornith 1.5-9B (Qwen3.5-based, 8-bit) as a local coding agent, with a stronger model writing its specs and plans. Learned from real engineering runs (October 2026); the rules apply to small local models in any agent harness.
 
 ## What it's good at
 - Mechanical engineering work: git merges (incl. a real conflict), detached remote jobs + polling, reading results, pushes.
@@ -11,14 +11,14 @@ How to get real work out of Ornith 1.5-9B (Qwen3.5-based, 8-bit / Bfp8) on one T
 - **Work is more reliable than its reports.** It mixes up similar events and states them confidently. Never trust its summary or the notes it writes into a plan; check against git and logs.
 - **It doesn't explore on its own.** A plain ask gets generic output; "read X first" gets accurate output.
 - **It doesn't know when it's done**, and doesn't push back on a task that makes no sense (an hour on an already-finished phase; 42 min re-verifying finished work).
-- **Thinking is the cost, not tools.** Reasoning blocks run 4–10k chars. Decode is fast at short context (~50 tok/s greedy with MTP, ~21.5 plain) but ~8 tok/s at 51k context.
+- **Thinking is the cost, not tools.** Reasoning blocks run 4–10k chars. On our hardware (one Tenstorrent p150) decode was ~50 tok/s at short context but ~8 tok/s at 51k context, so long thinking at long context costs minutes.
 - **Big reads fill its context fastest.** Given a function name in a 12,000-line file, it read 2,000 lines to find four functions; two reads added more context than all its reasoning.
 - **It skips saving its progress.** It treats "I understand it now" as done and moves to the next step without writing the result down.
 
 ## How to brief it
 - [ ] Name the exact files to read, in order.
 - [ ] **Give line ranges, not just names**: exact start–end lines for each function the step needs (e.g. `file.c:11966-12019`), and cap each read at ~150 lines. `grep -n` only finds where a function starts, so a name alone leads to huge reads.
-- [ ] **Absolute paths only.** The agent's working directory is usually not the code repo, and the read/edit tools may not expand `~`. Relative and `~` paths cost it three failed reads and a failed edit on its first code card.
+- [ ] **Absolute paths only.** The agent's working directory is usually not the code repo, and the read/edit tools may not expand `~`. Relative and `~` paths cost it three failed reads and a failed edit on its first code task.
 - [ ] **Small edits.** Each edit matches 1–3 lines of existing text; to add a block, match the one line it goes after. Large match blocks come out as unparseable tool calls and get dropped.
 - [ ] **Give the exact signatures and where code goes** (new small file vs which line of which file). Don't make it derive an API from a giant file.
 - [ ] **Small files are part of the brief.** If a step's target file is over ~1,000 lines, split it first (behaviour-preserving, gated) or hand over exact ranges.
@@ -27,7 +27,6 @@ How to get real work out of Ornith 1.5-9B (Qwen3.5-based, 8-bit / Bfp8) on one T
 - [ ] Include the stop rules: "if your task is already marked done, say so and stop"; "two failed checks → write `BLOCKED:` and stop".
 - [ ] Say where scratch files go (in the repo, never `/tmp`).
 - [ ] **Spell out every repo, path and branch.** For each kind of change (code, plan/spec, results), say which repo (full path), which branch, and which remotes to push to. An ambiguous rule ("work on branch X, never push to main" when the plan lives in a repo without branch X) stops it cold: it obeys the letter and marks the step blocked.
-
 - [ ] **Put the session protocol in the plan's START HERE block**, not in the human's prompt: what to read, do the first unchecked card only, save the result + check the box + commit, then stop; if already checked, say so and stop. Then the human's prompt is one line: "read `<plan>` and do the next card".
 
 ## How to run it
@@ -35,11 +34,11 @@ How to get real work out of Ornith 1.5-9B (Qwen3.5-based, 8-bit / Bfp8) on one T
 - [ ] **A card isn't done until its output is saved**: the written result in the plan/spec, the box checked, a commit. Only then start the next card (in a new session).
 - [ ] **Keep context small** (well under ~50k tokens): decode slows a lot past that, and when the agent compacts a long context the model can lose its place.
 - [ ] **The plan file is the memory**: every step leaves a one-line note in the plan, so a fresh session can resume.
-- [ ] For long remote jobs, expect sleep/poll loops that look like a hang; check `argus.log` before assuming it's stuck.
+- [ ] For long remote jobs, expect sleep/poll loops that look like a hang; check the agent's log or tool output before assuming it's stuck.
 - [ ] Double-check the files you hand it are the right ones (two similarly named plans cost an hour).
 
 ## Before anything lands
-- [ ] Verify its claims against git, the logs and the real files: the step that caught every bad note in Phase 1.
+- [ ] Verify its claims against git, the logs and the real files: the step that caught every bad note in our runs.
 - [ ] Only a human (or a stronger model on the human's go) merges or deploys.
 
 ## Split of labour