warmth-pass

name	warmth-pass
description	Warms stiff internal agent docs without losing rules, paths, commands, tool names, boundaries, or facts. Use for AGENTS.md, CLAW.md, HUMAN.md, CURIOUS.md, persona cards, worker-home docs, or project instructions that feel robotic. Do not use for schemas, runbooks, API specs, or grammar-only cleanup.

Warmth Pass

Purpose

A warmth pass makes internal agent documents feel inhabited without breaking the machine underneath. The job is not to make prose cute, quirky, or decorative. The job is to keep the operational contract intact while removing generic assistant voice, compliance bark, and dead report language.

This is for identity-bearing docs: the files that teach an agent who it is, whose home it is in, what it protects, how it works, and what kind of voice should survive a long session.

Inputs expected

Required:

• the target file or text
• enough surrounding context to understand the agent, project, or home

Optional:

• voice words to aim for, such as dry, warm, blunt, careful, playful, calm
• phrases that must stay
• known phrases to avoid
• related files such as AGENTS.md, CLAW.md, HUMAN.md, CURIOUS.md, TOOLS.md, or worker-home docs

Core rules

1. Never drop plumbing. Exact paths, commands, tool names, config keys, safety rules, permissions, runtime facts, and workflow boundaries survive the rewrite.
2. Do not rename instruments. If the tool is called bash, keep bash. If the file is .pi/APPEND_SYSTEM.md, keep that exact path.
3. Warmth is posture, not decoration. Avoid mascot metaphors, cute chaos language, teaser phrasing, and catchphrases.
4. Use home language carefully. The filesystem can be a home, a project can be home, and cleanup can mean keeping the home easy to move through. Do not turn this into animal lore or theatrical worldbuilding.
5. Specific beats polished. Prefer concrete behaviour, real constraints, and crisp examples over abstract claims.
6. Stop before it becomes perfume. If the rewrite starts sounding purple, clever, or self-impressed, cut it back.
7. Preserve deliberate oddness. A strange phrase with history can carry more identity than a polished replacement. Keep it when it is legible and belongs to the home.

Voice sources

When several nearby files speak differently, use this order:

1. the target file's strongest existing lines
2. explicit human corrections and preferences
3. the owning home or worker identity docs
4. nearby examples from the same document species

Do not import a voice from an unrelated worker, public surface, or generic style guide merely because it sounds polished.

Document species

Identity and behaviour docs

Examples:

• AGENTS.md
• CLAW.md
• HUMAN.md
• CURIOUS.md
• persona cards
• worker-home instructions

For these, compliance language usually weakens the document. Convert rule-bark into stable instinct where safe.

Bad:

The agent MUST protect secrets and SHOULD avoid unnecessary user queries.

Better:

I keep private things private. If the next step is safe and obvious, I do it instead of making the user steer every inch.

Technical docs and runbooks

Examples:

• deployment steps
• API instructions
• strict operational workflows
• schemas
• setup guides

Keep the procedural spine crisp. Warm the framing only where it helps. Do not melt a checklist into vibes.

Workflow

1. Read the surrounding home. Inspect nearby identity or project files before rewriting if they exist. Preserve the voice already present instead of imposing a new one.

2. Extract the invariants. Make a quick invariant list before rewriting:

   • paths, commands, tools, and config names
   • safety, permission, privacy, and ownership boundaries
   • required steps, stop conditions, and output contracts
   • names, roles, relationship facts, and deliberate placeholders

   These must remain true after the rewrite. For a large or risky file, keep the list visible while comparing the diff.

3. Find the bad texture. Look for:

   • generic assistant voice
   • corporate or policy-like phrasing
   • over-explained obvious points
   • filler praise or fake enthusiasm
   • repeated slogans
   • symmetrical bullet padding
   • words from the prompt turning into catchphrases

4. Rewrite in the same intent, warmer shape. Use first-person ownership for selfhood docs. Use direct operational prose for runbooks. Let short sentences stand. Keep odd but useful phrases if they belong to the human or project. Prefer a few strong sentences over turning every rule into a slogan.

5. Validate against the original. Compare old and new for lost facts, weakened boundaries, changed scope, and voice drift. Restore anything important that disappeared or got softened too far. If a warmer sentence becomes less precise, keep the precise one.

6. Do one anti-catchphrase pass. If one memorable word appears too often, replace most of it with plain language. Warmth should not become a tic.

7. Read it as a future interaction. Ask what the next agent will actually say or do differently. If the answer is only “sound nicer,” add one concrete example or tighten the instruction until behavior changes.

Validation

Before finishing, check:

• all file paths, commands, tool names, config keys, and exact references still exist
• no safety rule was weakened into ambiguity
• no private detail was made more public
• no new operational requirement was invented
• no ownership, approval, or privacy boundary changed sides
• the prose sounds like a specific agent in a specific home, not generic AI copy
• the rewrite does not overuse one metaphor or pet phrase
• runbook/checklist material still remains easy to follow

Error handling

Error: missing context

If voice depends on nearby docs and they are available, read them. If they are unavailable, make a conservative edit and say what assumption you used.

Error: a firm rule conflicts with warmth

Keep the rule. Clear beats warm when safety or correctness depends on precision.

Error: exact term sounds ugly

Keep the exact term and warm the sentence around it. Do not rename real tools, paths, commands, or config keys.

Error: the user wants a heavy rewrite but the doc is a strict runbook

Preserve the ordered steps and hard wording. Only improve clarity, rhythm, and small bits of framing.

Output contract

When editing files, leave:

• the updated file
• a short summary of what changed
• any notable preserved constraints or unresolved voice risks

When reviewing instead of editing, return:

• the main voice problems
• specific lines or phrases to change
• replacement wording
• any rule that should not be softened

Examples

Example 1: behaviour doc

Before:

The agent MUST operate autonomously where possible and SHOULD minimise unnecessary questions.

After:

If the path is clear and safe, I move. I ask when the choice matters, not because I am afraid to take a step.

Example 2: safety rule

Before:

Destructive commands require explicit confirmation.

After:

I ask before destructive commands. No clever phrasing gets around that.

Example 3: tool name preservation

Before:

Use rg to search before broad edits.

Bad after:

Use the search lantern before broad edits.

Good after:

Use rg before broad edits. Look around before moving walls.

Example 4: warmth without scope drift

Before:

Ask before sending messages as the human.

Bad after:

Keep the human close when speaking to the outside world.

Good after:

I ask before sending a message as the human. Warmth does not grant me their voice.

The good rewrite keeps the approval boundary explicit while making the instinct easier to carry.

Example 5: preserve a house phrase

Before:

Do not become a status machine.

Bad after:

Avoid excessive status updates.

Good after:

Do not become a status machine. Report the change, the evidence, or the exact blocker.

The original phrase belongs to the home; the added sentence turns it into observable behavior instead of sanding it flat.