Steering with PACK.md

Every pack has a PACK.md: how it operates, the words it should recognize, where its answers live, and what it doesn’t cover. Every question asked of the pack, and every task it runs, reads this first, whole, ahead of the first routing decision. A line here shapes every answer the pack gives.

It’s the one surface that changes how a pack works rather than what it knows. This guide is about writing and maintaining it. For the commands, flags, and preconditions, see edisyl pack context.

Steering vs. knowledge: route on which one is missing

A fact the pack should know is teach: definitions, documents, decisions. PACK.md is for what a document can’t carry.

The test: if you can imagine the sentence sitting in a document, teach it. If it’s an instruction to the pack about how to behave, it belongs here.

Steering (PACK.md)	Knowledge (teach)
“Every figure names which property it covers.”	The Q3 traffic report.
“Not in this pack: pipeline, roadmap. Say where it would live.”	The roadmap itself.
“the window = the first and last date a figure covers.”	The full metric definitions note.
“Messaging: taught documents only, never general knowledge.”	The messaging doc.

Getting this wrong is expensive in both directions. A definition buried in PACK.md is a fact nobody can cite or update, and it burns the budget every ask. A routing rule left in a document is a rule the pack will only apply if retrieval happens to surface it.

The suggested format

Three headings, one line per entry:

# Vocabulary

# Routing

# Workflows

Vocabulary is the words the pack can’t discover on its own. Internal nicknames, report names, the phrases people actually type, and what each one resolves to in the data or the knowledge base. Write the mapping, not the definition:

MER = marketing efficiency ratio = revenue / spend. Not ROAS; never quote one for the other.
the board deck = the monthly deck in Google Slides. Ask which link is current before citing it.

Routing is where answers live and where they don’t. Which source wins for a kind of question, what every answer has to carry, and the boundary of the pack. Say what’s out of scope explicitly: an unstated boundary is one the pack will try to answer across.

Spend and conversion figures: trust ad_platform_daily over anything taught. It's fresher.
"Qualified lead": trust the taught definition, never infer it from CRM stage names.
Not in this pack: pipeline, roadmap, customer research. Say where it would live.

Workflows is one line per routine, pointing at the pack’s knowledge for the details, never restating them. These read as standing instructions about how an answer should arrive:

Every figure arrives with its window as actual dates, never "all-time".
Weekly pacing check: see the pacing-review objective and its hint.
A trend claim needs a window that supports it.
When you cannot answer, name what is missing: a definition, a document, coverage, or a period.

Note what a good file never does: describe the business, restate a document, or spell out a metric in full. Those are facts, and facts belong in knowledge.

A whole file

Illustrative rather than lifted from a real pack; the shape holds regardless of the specifics. Three headings, one line per entry, no prose:

# Vocabulary

MER = marketing efficiency ratio = revenue / spend. Not ROAS; never quote one for the other.
the board deck = the monthly deck in Google Slides. Ask which link is current before citing it.
the site = acme.com only. The docs subdomain is a separate property with its own window.

# Routing

Spend and conversion figures: trust ad_platform_daily over anything taught. It's fresher.
"Qualified lead": trust the taught definition, never infer it from CRM stage names.
Positioning and messaging: taught documents only, never general knowledge. Cite the document.
Not in this data: CAC, channel ROI, paid attribution. The CRM columns are join keys only.
Not in this pack: pipeline, roadmap, customer research. Say where it would live.

# Workflows

Every figure arrives with its window as actual dates, never "all-time".
Weekly pacing check: see the pacing-review objective and its hint.
New campaign checklist: routes to the domain pack's playbook, not to general knowledge.
A trend claim needs a window that supports it.
When you cannot answer, name what is missing: a definition, a document, coverage, or a period.

The file is small on purpose

A write replaces the whole file, and the cap is 10,000 characters. Every ask and every task pays its token cost, so it’s a product surface, not a scratchpad.

That budget is the discipline. When a new line is needed, look for the two it replaces. Push details down into knowledge and leave a pointer here. If a section is growing, it’s usually because facts have leaked into it.

Tip

Read it before you write it. set replaces the entire file with what you send, so a write built from a stale copy silently drops everything added since.

Three ways it gets updated

Teaching keeps it current. Anyone with write access can teach the pack, and the pack’s curator writes PACK.md as it learns: new vocabulary it saw resolve, boundaries it discovered the hard way. This is the default path, and it means the file drifts toward accuracy on its own.

Owners edit it directly, for precision control. edisyl pack context edit <pack> opens it in your editor and conditions the save on the version it opened, so a teach that lands while you’re typing is refused rather than overwritten, with your draft left on disk. Everything except reading is owner-only.

Reverting undoes a bad line without erasing it. history shows who changed the guidance, when, and whether it came from a hand edit, a teach, a prune, a revert, or an import. revert writes the chosen version forward as a new revision, so the changelog stays append-only.

Because both people and the curator write here, treat a refused save as normal. Re-read, fold your change into what’s now there, and write again.

When to reach for it

• An answer used the wrong source, and the right one is obvious to you but not to the pack. → Routing.
• Someone asked using an internal name and the pack didn’t recognize it. → Vocabulary.
• The pack confidently answered something it has no business answering. → Routing, as an explicit boundary.
• Answers are right but keep arriving without the caveat they need. → Workflows.
• The pack didn’t know a fact. → Not this file. teach it.