ailiteracynepal 🇳🇵
Text size

Chapter 03 · Section II · 10 min read

3.2 Reusable knowledge: so no run starts from zero

The stable context every cycle needs, loaded before the work begins. Conventions, playbooks, directory maps — the things that shouldn't have to be re-derived on every run.

Every cycle needs to know some things that don’t change from run to run — your project’s conventions, your team’s terminology, the specific rules of your domain. Loading that context every cycle by asking the model to figure it out from scratch wastes tokens and produces inconsistent output. Storing it as reusable knowledge means every cycle starts from the same base.

What counts as reusable knowledge

Anything that’s:

  • Stable. Doesn’t change from one cycle to the next. If it changes weekly, it’s still probably worth writing down (and updating weekly).
  • Non-obvious. The model wouldn’t know it from general training. Your product’s specific tag taxonomy. Your team’s tone rules. Your codebase’s directory map. Your industry’s compliance requirements.
  • Referenced repeatedly. If every cycle asks the model to remember “we always use two-space indentation, we never use console.log, tests live in tests/ not __tests__/,” that’s reusable knowledge you should write down once.

What’s not reusable knowledge:

  • The task itself. The task changes per cycle; it goes in the trigger’s payload.
  • Yesterday’s decisions. Those are memory (Chapter 4), not knowledge — they’re dynamic.
  • Anything a README already says. Point at it instead of duplicating it.

Where reusable knowledge lives

Three common shapes:

A single file loaded on every cycle. A CONVENTIONS.md, a PLAYBOOK.md, or an equivalent — a short, curated document read into context at the start of every cycle. Works when the knowledge is small (a few pages) and applies to every cycle equally.

A folder of skill-scoped files. Different cycles need different knowledge. A folder like skills/ with one file per skill; the loop loads the file relevant to the current task. Scales better than one giant file when you have many distinct kinds of cycles.

An external retrieval system. Once the knowledge is genuinely large (hundreds of docs, a full policy handbook, a codebase), you index it and let the cycle retrieve the relevant chunks rather than loading everything. RAG territory; see 5.5 in the Prompt Engineering course.

Most loops start with a single file, graduate to a folder, and only reach for retrieval when the knowledge is genuinely too big to fit.

What good reusable knowledge looks like

The best examples are short, specific, and action-oriented:

Good:

  • “The frontend lives in apps/web. Do not touch apps/legacy.”
  • “Every user-facing string must go through t() in src/i18n/.”
  • “We use tabs. We use vitest. Tests live next to source files as *.test.ts.”
  • “For customer messages, our tone is warm but not gushing. No exclamation marks. Do not use ‘unlock’, ‘seamless’, or ‘leverage’.”

Bad:

  • A 40-page architecture whitepaper. Nobody — including the model — will read it every cycle.
  • “Try to be helpful and accurate.” The model already tries to be helpful and accurate. This adds nothing.
  • Anything phrased as “please” or “kindly.” Reusable knowledge is a spec, not a request.

The rule of thumb: if a new engineer’s first-day onboarding notes would say it, put it in reusable knowledge. If the notes wouldn’t, don’t.

The version-drift problem

Reusable knowledge rots. Six months from now, you’ll rename apps/web to apps/frontend and forget to update the file. The loop will keep telling itself “the frontend lives in apps/web” — a directory that no longer exists.

Two habits that help:

  • Own it. One file, one owner, one place. If three copies of the playbook exist in three places, at least two are wrong.
  • Review on commit. When you rename a directory, restructure the codebase, change a convention — update reusable knowledge in the same pull request. Not later. There is no “later.”

The cost of getting it wrong in the other direction

Reusable knowledge that’s wrong is worse than no reusable knowledge. Every cycle will confidently apply the wrong rule, and (because the model treats it as authoritative) it’ll take longer to notice than a random one-off mistake would.

Concrete example: a reusable-knowledge file that says “we use console.log for all logging” when the codebase actually uses pino. Every cycle now writes console.log calls. The loop appears to be working — output is generated, tests may even pass — but every cycle is degrading the codebase.

Defence: whenever you notice the loop consistently doing the wrong thing, check reusable knowledge first, not the prompt.

Scoping: what belongs where

Not all knowledge belongs at the same scope:

  • User-level: conventions you personally follow across all your projects. “I prefer functional style over classes.”
  • Project-level: conventions specific to this project. “This project uses Astro; not Next.js.”
  • Task-level: conventions specific to a kind of task. “Customer-support drafts follow this specific tone.”

Batteries-included tools usually have opinions about where each scope lives. Assemble-your-own means picking the split yourself. Keep the levels distinct; a project-level rule mixed into user-level knowledge will leak into projects it shouldn’t apply to.

Check your understanding

Quick check

—

Which of the following is the STRONGEST candidate to write down as reusable knowledge for a loop that drafts customer-support replies?