Codebase Teach

<!-- MEMORY-CONTRACT v1 -->

Memory contract

Standing contract for every invocable command. Rendered once per command

file into the per-tool envelope by config-export command mode. Expresses

cross-session persistence in tool-neutral prose — it issues NO tool-specific

call, so it passes the export STRIP guard verbatim.

This command persists its work across sessions through engram, registered as an MCP server in this tool. Use this tool's own engram memory tools to honor the contract below — do not assume any other persistence layer.

Recall before acting

When the first input is a continuation keyword ("listo", "dale", "seguimos", "ready", "where did we leave off", "qué sigue"), DO NOT start fresh. First search engram for prior work on this change — by the change name and by recent topic keys — then summarize what you found and continue from there. Skipping the search and asking "what can I help with?" means you ignored existing context.

Validate after saving

After any save, verify it actually persisted: search engram back for the key or a unique phrase you just wrote. A tool response of "saved" is NOT proof the row landed. If the verifying search does not return the row, retry once; if it still fails, tell the user the save failed — never report "saved" on the tool response alone.

Summarize at close

Before ending a session, write a session summary to engram (goal, what was done, decisions, next steps, relevant files) so the next session can recover context. Recovery is never automatic — every session must search engram to find prior state.

When engram is unreachable

If engram is not installed or not on PATH, memory operations cannot persist. When that happens, emit a visible warning to the user that engram was not found (not installed / not on PATH) and that this session's work will NOT survive. DO NOT report memory as saved, and DO NOT proceed silently as if persistence had occurred. See the install prerequisite in the onboarding docs to enable engram.

Skill Logic: codebase-teach

Analyzes bounded contexts from the project's source tree, extracts domain

knowledge per context, writes ai-context/features/<context>.md files, and

produces teach-report.md with coverage metrics. Tool-neutral logic — no

harness-specific wiring.

Purpose

codebase-teach fills the ai-context/features/ layer with structured domain knowledge derived from reading source code. It is the deep-read complement to memory update (which records session decisions) and memory init (which scaffolds empty stubs). It MUST only be invoked manually by the user.

---

Process

Step 0 — Load project context (non-blocking)

This step is non-blocking: any failure (missing file, unreadable file) MUST produce at most an INFO-level note. This step MUST NOT produce status: blocked or status: failed.

1. Read ai-context/stack.md — tech stack, versions, key tools. 2. Read ai-context/architecture.md — architectural decisions and rationale. 3. Read ai-context/conventions.md — naming patterns, code conventions. 4. Read the project's instruction file (at project root) and extract the ## Skills Registry section.

For each file:

• If absent: log INFO: [filename] not found — proceeding without it.
• If present: extract Last updated: or Last analyzed: date. If date is older than 30 days: log NOTE: [filename] last updated [date] — context may be stale. Consider running /memory-manage or /codebase-teach.

Also read project config file (config.yaml at project root) if it exists, and extract teach_max_files_per_context if present:

• If present: max_files = teach_max_files_per_context
• If absent: max_files = 10 (default)

Log: "File cap per context: [max_files] (source: config.yaml)" or "File cap per context: 10 (default)"

---

Step 1 — Scan bounded contexts

Identify bounded context candidates by scanning the project directory tree at depth ≤ 2 under these root directories (in order):

1. src/ — subdirectories at depth 1 (e.g., src/auth/, src/payments/) 2. app/ — subdirectories at depth 1 3. features/ — subdirectories at depth 1 4. domain/ — subdirectories at depth 1 5. ai-context/features/ — existing feature file names (each file stem is treated as a context name)

Exclusion rules — skip directories named: shared, utils, common, lib, types, hooks, components, __tests__, test, tests, node_modules, .git

Cross-reference with existing feature files: Read the ai-context/features/ directory (if it exists) and list all .md files, excluding files whose names begin with _ (e.g., _template.md).

For each detected context candidate, build a record:

{ slug: kebab-case of directory name, dir_path, existing_feature_file: bool }

Slug convention: lowercase the directory name; replace spaces and underscores with hyphens. Example: UserProfile → user-profile, auth_service → auth-service.

If no context candidates are found:

• Log: "No bounded context directories detected."
• Write teach-report.md with a Summary noting "No bounded context directories detected" and a recommendation to run /memory-manage first.
• Stop here.

If `ai-context/features/` does not exist:

• Log: "INFO: ai-context/features/ not found — feature files will be created if possible."
• Note in teach-report.md: "ai-context/features/ was absent at run time. Recommend running /memory-manage to scaffold the directory before re-running /codebase-teach."
• Continue processing (the skill creates the directory and files as needed).

Output: context_list = [{ slug, dir_path, existing_feature_file: bool }, ...]

Log each context found: "Detected context: [slug] — [dir_path] (feature file: [exists|absent])"

---

Step 2 — Read key files per context (sequential)

Process contexts one at a time. For each context in context_list:

1. Enumerate implementation files in dir_path (recursive), filtering for file extensions: .ts, .tsx, .js, .jsx, .py, .java, .kt, .rb, .go, .ex, .exs, .cs, .rs, .php, .swift

• Prioritize files by recency (most recently modified first)
• Exclude files matching: *.test.*, *.spec.*, test_*, *_test.*, *.d.ts, *.min.*

2. Apply file cap: read at most max_files files. If total enumerated > max_files, log: "[slug]: [total] files found — sampling [max_files] (cap applied)"

3. For each file to read:

• Attempt to read the file
• If the file is binary or unreadable: skip it; record in skipped_files with reason
• If readable: extract the following signals:
• Business rules: explicit conditional constraints (if/when/unless logic that enforces domain rules)
• Invariants: assertions or validation guards that are always enforced
• Data model entities: class/struct/interface/type names with their key fields
• Integration points: imports of external services, APIs, or infrastructure adapters

4. Accumulate: context_knowledge = { slug, rules[], invariants[], entities[], integrations[], files_read[], skipped[] }

---

Step 3 — Write ai-context/features/<slug>.md

For each context processed in Step 2:

If `ai-context/features/<slug>.md` does not exist (or ai-context/features/ is absent):

• Create the directory if needed
• Write a new file using the six-section structure below
• All AI-generated sections receive [auto-updated] markers

If `ai-context/features/<slug>.md` already exists:

• Read the entire file
• Identify <!-- [auto-updated]: codebase-teach ... --> ... <!-- [/auto-updated] --> blocks
• Overwrite content only inside [auto-updated] blocks
• Preserve byte-for-byte all content outside any [auto-updated] block
• If no [auto-updated] block exists for a section, append the section at the end of the file inside a new [auto-updated] block

Six-section feature file structure: the canonical contract lives in skills/_templates/feature/_template.md — read it and use its exact section structure, headings, and [auto-updated] markers. Do NOT inline a copy of the structure here; the template is the single source of truth, shared with the feature-define and feature-domain-expert skills. Set Last updated by: codebase-teach and Last run: to today's date when writing.

The six sections, in order, are: Domain Overview, Business Rules and Invariants, Data Model Summary, Integration Points, Decision Log, Known Gotchas — each wrapped in a <!-- [auto-updated]: codebase-teach … --> block per the template.

`_template.md` guard: never treat any file whose name begins with _ as a feature context to extract from — skip such files when scanning. This guard does NOT block reading _templates/feature/_template.md as the structural contract above; that read is required, not a feature extraction.

---

Step 4 — Evaluate coverage and write teach-report.md

Coverage calculation:

documented_contexts = count of contexts that have an ai-context/features/<slug>.md file after Step 3
total_contexts      = count of contexts in context_list
coverage_pct        = (documented_contexts / total_contexts) * 100   (0 if total_contexts == 0)
gap_list            = contexts in context_list where existing_feature_file was false before Step 3
                      AND no file was created in Step 3

Write `teach-report.md` in the project working directory root (same level as analysis-report.md). Overwrite if it exists.

# Teach Report — [Project Name]

Last run: YYYY-MM-DD
Skill: codebase-teach

## Summary

Contexts detected: [total_contexts]
Contexts documented: [documented_contexts]
Coverage: [coverage_pct]%

## Coverage

[coverage_pct]% — [documented_contexts] of [total_contexts] contexts documented.

## Gaps

Contexts detected in code but not documented in ai-context/features/:

- [context-slug] — [dir_path]

[If no gaps: "None — all detected contexts are documented."]

## Files Read

### [context-slug]
- [file path] — sampled
- [file path] — sampled
- [file path] — SKIPPED: [reason]

[Repeat for each context]

## Sections Written / Updated

- ai-context/features/[context].md — [created|updated] — sections: [list of sections written]

If ai-context/features/ was absent at run time, append to the Summary section:

Note: ai-context/features/ was absent at run time. Recommend running /memory-manage to scaffold the directory before re-running /codebase-teach.

---

Rules

• MUST NOT modify ai-context/stack.md, ai-context/architecture.md, ai-context/conventions.md, ai-context/known-issues.md, or ai-context/changelog-ai.md
• MUST NOT modify any file under docs/
• MUST NOT be invoked automatically by any other skill — user-initiated only
• MUST skip any file or directory whose name begins with _ in ai-context/features/
• MUST preserve all human-authored content outside [auto-updated] markers when updating existing feature files
• MUST process contexts sequentially — never in parallel
• MUST apply the teach_max_files_per_context cap (default 10) to every context
• MUST list skipped files in teach-report.md under the "Files Read" section for the relevant context
• MUST complete without error even when no bounded context directories are detected
• MUST write teach-report.md on every successful run
• [auto-updated] marker format: <!-- [auto-updated]: codebase-teach — last run: YYYY-MM-DD --> ... <!-- [/auto-updated] --> — consistent with codebase-teach convention

---

Output

teach-report.md (mandatory — written to project root on every run)

Required sections:

ai-context/features/<context>.md (one per bounded context)

Written or updated during Step 3. Six sections with [auto-updated] markers on all AI-generated content.