Changes: - SKILL.md cut to ~1400 tokens (from ~2500+) - Schema examples moved to references/ - Project tiers: Nano/Small/Large - Mid-session re-anchor rule (every 15+ tool calls) - SESSIONS + ERRORS + LEARNINGS archives - Wrong-turn report format with error logging - Collapsed session end to 5 steps + self-reflection - Pending errors check at session start - DEPS.md template for dependency tracking - learnings-guide.md reference doc - GUIDE.md: comprehensive user guide (shared with SmallClaw) - README.md rewritten with comparison table
9.1 KiB
Working With Your AI — A User's Guide
This guide is for you, the human. The SKILL.md teaches the model how to work. This teaches you how to work with the model — especially small ones.
The Single Most Important Thing
Small models are literal. They do exactly what you say, not what you mean. The gap between those two things is where all the bugs come from.
"Fix the login" → model edits a random auth file it hasn't read, invents a function name, breaks something else.
"Read auth.py, then fix the password validation in validate_login() — it's accepting empty strings" → model reads the file, finds the function, fixes exactly that.
The difference isn't intelligence. It's that you gave it a target.
How to Give Good Tasks
Be specific about WHAT, not HOW
Bad: "Make the API faster" Good: "The /api/scan endpoint takes 9 seconds. Profile it and find the bottleneck."
Bad: "Add error handling" Good: "scanner.py crashes when fping isn't installed. Add a check at startup that fails with a clear message."
The model should figure out how. You should be precise about what and where.
Name the files
Small models don't have your mental map of the project. When you know which file is involved, say so:
"In main.py, the /api/port-scan endpoint is returning cached results even after a fresh scan."
This saves the model from guessing — and guessing is where hallucination starts.
One task at a time
Bad: "Add port scanning, fix the UI, and also update the README" Good: "Add port scanning to the scanner module. We'll do the UI next."
SmallClaw enforces this through STATUS.md (one Current Task), but it starts with you. If you dump 3 tasks, the model will try to do all 3, context will fragment, and quality drops.
Say when you DON'T know
"The proxy is broken but I'm not sure why — start by reading main.py proxy routes and telling me what you find."
This is a perfectly valid task. You're asking the model to investigate, not fix blindly. Much better than "fix the proxy" when you don't know the root cause.
How to Talk About Scope
Starting a session
Best opening: check what the model thinks it should do.
"Read STATUS.md and tell me what's current."
If it gets that right, you're aligned. If not, correct it:
"No, we finished that. Current task is the theme switcher. Update STATUS.md."
Expanding scope mid-task
This is the #1 cause of drift. You ask for one thing, then "oh also..." twice, and now the model is juggling 3 things with no clear boundary.
Instead:
"Park this — commit what you have, update STATUS.md, and let's switch to the proxy bug."
SmallClaw's session-end protocol exists for this. Use it even mid-session when switching tasks.
Narrowing scope
"That's more than I wanted. Just do the fping discovery part — skip the port scan for now. Update CONTEXT.md to only include scanner.py."
Explicitly telling the model to update CONTEXT.md forces it to re-scope. This works better than "don't touch that file" because it's written down, not just said.
How to Correct Mistakes
Wrong approach
"Stop. That's not what I meant. Don't edit any more files."
Then explain what you actually wanted. The model should report a WRONG TURN and wait.
Wrong file / wrong function
"You're editing the wrong file. The auth logic is in auth.py, not main.py. Re-read CONTEXT.md."
Referencing CONTEXT.md gives the model a concrete action — not just "you're wrong."
Hallucinated code
"That function doesn't exist. Read scanner.py and list the actual function names before trying again."
Force a read. Always. "List what's actually there" is the best anti-hallucination prompt.
Repeated mistake
"This is the third time you've used the wrong import path. The correct import is from scanner import scan_lan_stream, not from utils.scanner. Write this down in ARCH.md decisions log so it sticks."
With SmallClawPlus: "Log this as a learning." (It has the .learnings/ system for exactly this.)
With SmallClaw: ARCH.md decisions log or SESSIONS.md gotcha bullet. Less structured, but it works.
How to Handle Long Sessions
The drift problem
After ~30 minutes of active coding (roughly 50-80 tool calls), models start "forgetting" earlier context. Signs:
- Re-reading files it already read
- Contradicting decisions it made earlier
- Inventing things instead of checking
What to do about it
Trigger a re-anchor: "Re-read STATUS.md and CONTEXT.md, then tell me where we are."
This costs almost nothing and resets the model's working memory. SmallClaw's SKILL.md tells the model to do this automatically after 15+ tool calls, but you can trigger it manually anytime you notice drift.
Commit and summarize: "Commit what you have, write a SESSIONS.md entry, and let's continue."
Mid-session commits act as save points. If things go wrong later, you have a clean rollback.
Break long tasks into phases: Rather than "build the entire proxy system," break it up:
- "Phase 1: route matching. Just get
/proxy?t=URLto fetch and return the page." - "Phase 2: link rewriting. Make relative URLs work through the proxy."
- "Phase 3: SPA handling. Intercept JS navigation."
Each phase is a commit. Each phase starts with the model re-reading its scope. Drift resets naturally.
How to Review Work
Before accepting
"Show me what changed: git diff --stat and git log --oneline -5"
Don't just look at the output of the last command. Check what files were actually modified.
The brain files check
"Read STATUS.md — is it current?"
If the model has been maintaining STATUS.md throughout the session, it should match reality. If it doesn't, the model drifted and you should review more carefully.
Spot-checking on small models
Small models skip steps when rushed. After a complex task:
"Did you update CONTEXT.md for the next task? Show me."
"Is SESSIONS.md up to date? Show the last entry."
These take seconds and catch common omissions.
How to Start a New Project Right
The init conversation matters more than you think. Here's what good looks like:
You: Start a new project — TailScan. It's a LAN scanner
web app that discovers devices through Tailscale
exit nodes. Python/FastAPI backend, vanilla JS
frontend. 5-10 files probably.
AI: Got it. That's Small tier (5-20 files). Milestones?
You: 1. Basic scan — discover devices on LAN via fping
2. Port scanning — nmap per device
3. UI — web dashboard with live updates
AI: Forge?
You: Gitea — git.rewr.ca/Dragon/TailScan
AI: Any domain terms?
You: Exit node = Tailscale peer that routes traffic to
its local network. Subnet route = the CIDR the
exit node advertises.
Now the model creates brain files with real content — not generic placeholders. The glossary has actual terms. The plan has actual milestones. STATUS.md points to a real first task.
Model Size Tips
Small models (8B–30B) — Qwen, Gemma, Phi, Llama small
- Always name files explicitly in your task description
- One task, one module — no cross-cutting work
- Trigger re-anchors often — every 10-15 tool calls
- Check brain files after every session — small models skip steps more
- Keep CONTEXT.md tight — 3-5 files max per task
- Use Nano tier for scripts and small tools
Medium models (30B–70B) — Qwen 72B, Llama 70B, Mistral Large
- Can handle Small tier with modules
- Less hand-holding on file names, but still be specific on what
- Re-anchor every 20-30 tool calls
- Can maintain ARCH.md decisions log reliably
Large models (100B+) — Sonnet, Opus, GPT-4, Qwen 110B+
- Consider SmallClawPlus for the learnings system
- Can handle cross-module tasks (but still declare scope in CONTEXT.md)
- Re-anchor every 30-50 tool calls, or on signs of drift
- Most value from: decisions log, SESSIONS.md continuity, multi-project isolation
Common Failure Modes and Fixes
| Symptom | Cause | Fix |
|---|---|---|
| Invents function names | Didn't read the file | "Read {file} first, list what's there" |
| Edits wrong file | Lost track of scope | "Re-read CONTEXT.md" |
| Contradicts earlier decision | Context drift | "Re-read STATUS.md and SESSIONS.md" |
| Skips brain file updates | Instruction overload | "Update STATUS.md now, before coding" |
| Commits to main | Forgot branch rule | "You're on main. Create branch first" |
| Giant single commit | Didn't commit incrementally | "Commit what's done. Then continue" |
| Task keeps expanding | Scope creep in conversation | "Park this. Commit, update STATUS.md, re-scope" |
| Same error 3 times | No persistent memory | "Write this in ARCH.md decisions log" |
Quick Reference
Start of session: "Read STATUS.md and tell me what's current."
Give a task: Name the file, describe what's wrong or wanted, one thing at a time.
Mid-session drift: "Re-read STATUS.md and CONTEXT.md."
Scope change: "Commit what you have, update STATUS.md, switch to {task}."
Something broke: "Stop editing. Show me git diff. What went wrong?"
End of session: "Wrap up — session end protocol."
Check quality: "Show me STATUS.md, CONTEXT.md, and git log."