Knowledge

The knowledge system

Guild Stack keeps project knowledge in two places. /guild:learn builds maps and graphs of the code under .guild/indexes/ and .guild/knowledge/. /guild:wiki keeps the synthesized knowledge and decisions in .guild/wiki/.

Learn

/guild:learn with no sub-verb runs the full pipeline. First it detects the target's shape and asks you to confirm it. The shapes are regular_project, workspace, existing_guild_project, new_or_sparse_project, and mixed_or_uncertain. A deep graph build shows a cost estimate before it runs. In a workspace, Guild Stack detects the child repos first and never scans them as one monolith.

/guild:init --learn runs the same learn chapters. There is one implementation with two triggers. An unknown sub-verb prints usage and writes nothing.

Wiki

guild-wiki also captures decisions: ask it to record a decision, or ask what was decided about a topic.

Who writes the wiki

• Ingest is human-gated. A source becomes a candidate; only the gate lands it.
• Harvest is the only automatic writer. It runs when wiki.autopromote is on (the default). Set it to false to keep this root candidates-only.
• Reflection never writes the wiki. guild-reflect writes proposals to .guild/reflections/<run-id>.md.
• Every learn promotion is human-gated.

Recall

query ranks results with BM25. Set recall.backend: hybrid to add a cache-only rerank on top. If the rerank fails, the query falls back to BM25.

Undo

/guild:maintain wiki revert inverts a harvest using the harvest journal.

Learn in depth

/guild:learn builds Guild Stack's understanding of your codebase. It runs in tiers, from a cheap scan to a deep knowledge graph. Each deeper tier is gated by cost. It writes only derived indexes and candidates. Nothing is promoted into the wiki without you. For how the wiki and recall work, see Knowledge.

Try it

/guild:learn                 # smart full learn: detect, confirm, run the pipeline
/guild:learn map             # cheap scan only
/guild:learn explain <file>  # deep-dive one file, module or concept

An unknown sub-verb prints usage and stops. No skill runs and no file is written.

The seven modes

Every mode is a chapter of one assembler skill. The first token picks the chapter and the rest is passed on. The assembler also has a harvest chapter for extracting knowledge from phase and run artifacts. It is not listed as a sub-verb in the command.

One implementation, two triggers

The same learn-* chapters run from /guild:learn and from init. A plain /guild:init stops at the cheap scan. Init runs the full pipeline when you pass --learn or set defaults.auto_learn: true (default false).

There is no per-trigger branch that changes output. The knowledge tier produces byte-identical artifacts from /guild:learn knowledge, the full learn and init --learn, at a given commit. Under --learn init adds a summary line only, and under defaults.auto_learn the capability report is written with no prompt.

Tiers and gates

Tier 1, cheap scan. Deterministic scripts do the scan and write the CodebaseMap. Every model call in this tier is the cheap tier. It never uses powerful.

Tier 2, deep graph. Before it runs, Guild Stack shows the file count and a time estimate and asks [Y/skip]. There is no hidden auto-run on large repos. If you skip, the run records the refusal and continues. The map and the deterministic knowledge-links.json are still produced.

Tier 3, knowledge tier. A cost gate returns one of three verdicts:

• pass: proceed silently.
• confirm: show the estimate and continue only if you approve.
• abort: stop and show the reason.

A staleness check then decides whether to run at all. If no K-stage is stale, the tier is skipped.

Model tiers: reading and summarizing use cheap. Categorizing and relationship extraction use mid. Edge validation uses powerful, and only past a configurable edge-candidate threshold or when a mid stage escalates. Recall runs first: if recall returns a chunk with a top score at or above models.recallScoreThreshold (default 0.4), the full read is skipped.

What gets detected

The no-argument form classifies the target as one of regular_project, workspace, existing_guild_project, new_or_sparse_project or mixed_or_uncertain. It shows the result and asks before it proceeds. The run starts before any scan.

On a workspace, Guild Stack never scans the child repos as one monolith. Each child is registered and learned on its own, with its own .guild/. Fan-out follows learn_fanout: auto (default) fans out after an aggregate cost estimate, and plan-only writes a plan and stops. --dry-run always behaves as plan-only. Cross-project knowledge lands as wiki candidates in the root. At workspace scale the knowledge tier does not run by default; run /guild:learn knowledge yourself.

Staleness classifier

Guild Stack compares a stored fingerprint to the working tree and reports one verdict. The verdict is advice. The script exits 0 and never rebuilds anything.

--baseline re-seeds the fingerprint after a build. Act on the verdict only when you or a reflection trigger asks. It is never a silent mid-task rebuild.

The knowledge tier: K1 to K6

The tier enriches the structural graph into guild.knowledge_graph.v2. It needs the structural graph first. If knowledge-graph.json is missing, run /guild:learn graph.

Scripts propose candidates, each with a stable key. The model only judges them, and a key outside the candidate set is ignored. A final deterministic step applies the judgments and writes the files. The model never writes the byte-compared artifacts. Cross-links are proposed from shared anchors or terms, then confirmed by the model. They are never invented.

Three index files, not one

Do not confuse these. All are derived, deletable and rebuildable.

Output locations

Some files are always skipped: binaries, vendored code, build output, secrets, and files over the size limit. Lockfiles, .gitignored paths and oversized files can be included with --include-lockfiles, --include-gitignored or --include-oversized=<bytes>. Each skip is recorded with its reason.