Compound

Knowledge compound

Contract

Inputs

• Session transcript (required): the accumulated context of the current session, from which learnings are extracted.
• docs/solutions/ directory (optional): the shared learning-doc store, also written by autolearn. An absent directory counts as an empty store and is created on the first approved write.

Procedure

1. Scan docs/solutions/ recursively (**/*.md, excluding README.md) for existing records. Load each record and extract its frontmatter tags, type, and source. Records written by autolearn live in category subdirectories and carry its own schema; read them for overlap, never rewrite them to this schema. Done when: every existing record is loaded with its frontmatter.
2. Check for stale and conflicting entries: compare the extracted tags of each existing record against the candidate learnings. An entry is stale when its tags overlap with a new candidate and its content contradicts or supersedes the candidate. An entry conflicts when it shares tags but states the opposite. Flag each stale or conflicting entry by name with the overlap reason; do not delete or overwrite it. Done when: every stale or conflicting entry is flagged by name with its overlap reason.
3. Propose at most three specific learnings drawn from the session transcript. Classify each with a type (e.g., pattern, caveat, reference, decision, concept, fix, lesson). Reject a fourth or fifth as scope creep; propose none if the session yielded no durable learning. Done when: at most three learnings are proposed with types, or an honest none is proposed.
4. For each proposed learning: a. Check against the stale-knowledge inventory: if a duplicate or contradiction exists by shared tag, flag it explicitly rather than overwriting. Done when: the duplicate or contradiction is flagged or none exists. b. Assign retrieval tags, confidence level (high/medium/low), date (ISO 8601), and source context. Done when: tags, confidence, date, and source are assigned. c. Draft frontmatter per the Record schema below: type, tags, confidence, date, source, Context (what triggered the learning), Implication (what changes as a result). Done when: frontmatter is drafted with all seven fields.
5. Present the proposed records to the user for approval. Include the stale/conflict flags so the user can decide whether to update, merge, or consolidate. Done when: the proposed records and flags are presented for approval.
6. On user approval: write each approved record to docs/solutions/{slug}.md using the drafted frontmatter and a prose body derived from the session. If a record updates or consolidates an existing entry, preserve the original entry's history line. Done when: every approved record is written with valid frontmatter and history preserved.
7. Confirm completion by naming the retrieval tags for each saved record. Done when: the retrieval tags for each saved record are named in the confirmation.

Failure and recovery

Output

Markdown files written to docs/solutions/ (or the configured directory), each with frontmatter (type, tags, confidence, date, source, Context, Implication), plus a terminal confirmation naming retrieval tags for each saved record.

Record schema

Canonical frontmatter contract for docs/solutions/{slug}.md records. All seven fields are required.

Body

Prose body derived from the session, expanding on Context and Implication with the substance of the learning. No fixed section structure; let the learning shape dictate the prose.

Filename

{slug}.md: a sanitized, descriptive slug derived from the learning's core idea. No date suffix (the date field carries that).

YAML safety

Wrap array items in double quotes when a value starts with any of: ` [ ] { } , * & ! | > % @ ?. Also quote when a value contains ": ". Scalar fields have a separate failure mode: an unquoted # truncates at the comment, an unquoted : reframes as a mapping.

Consolidation

When a new record supersedes or contradicts an existing entry (flagged in step 2), the user may approve a consolidation: merge the new record into the existing file, preserve the original as a history line, and update the frontmatter date and Context/Implication to reflect the consolidated state. Never silently delete the superseded entry.

Vocabulary capture: CONCEPTS.md (optional)

When a durable project term with a precise local meaning surfaces during curation, reconcile CONCEPTS.md per references/concepts.md. The glossary is a shared surface; follow the one-definition-per-concept discipline. This is optional and never blocks the primary curation flow.