Debriefs

Turn everything you learn into a compounding knowledge base — without doing any of the work.

Debriefs is a framework for Claude Code that builds and maintains a self-evolving knowledge wiki. You drop files in a folder. The AI compiles them into structured, cross-linked pages that get smarter over time.

Debriefs is the learn stage of A Player OS: Playbooks (build) → Operatives (run) → Debriefs (learn) → Assets (compound). Debriefs extracts what was learned and feeds it back as briefs that sharpen future playbooks.

Inspired by Andrej Karpathy's LLM Knowledge Bases.

Who this is for

Anyone who reads, researches, or learns — and wants that knowledge to compound instead of evaporate into browser history. Works solo or as a team.

The knowledge lifecycle

Every piece of knowledge flows through four stages:

Logs → Findings → Debriefs → Briefs

• Logs — raw source material. Drop a URL, a transcript, a PDF into raw/. No formatting, no tagging.
• Findings — compiled wiki pages. /compile reads your logs and produces structured, cross-linked pages in wiki/.
• Debriefs — the wiki as a whole. Cross-linked findings that form your organisational knowledge base.
• Briefs — distilled output handed back to Playbooks to improve future work.

How it works

You find something interesting
      |
/save                    Save it (one command, auto-pushes)
      |
/compile                 AI reads your logs, writes findings
      |
/query                   Ask your wiki anything
      |
/lint                    Catch broken links, stale pages, missing sources
      |
/evolve                  The system observes its own patterns and improves

Your wiki is markdown files with frontmatter. Git is the database. GitHub is the backup. Obsidian is the optional viewer. There is no backend, no database, no service to maintain.

Install

git clone https://github.com/aplayerlabs/debriefs.git ~/.claude/skills/debriefs
cd ~/.claude/skills/debriefs && ./setup

Then open Claude Code in a new repo and type /init.

Skills

Command	What it does
/debrief	Start here. Reads your wiki state, tells you what to do next.
/init	Bootstrap a new debrief wiki — folders, templates, GitHub Actions.
/save	Save something to your wiki. Paste a URL, text, or describe what to save. Handles file creation and git push.
/compile	Compile new logs into findings (wiki pages).
/query	Ask your wiki a question. Valuable answers get deposited back as new logs.
/lint	Run integrity checks — frontmatter, links, staleness, orphans.
/evolve	Monthly evolution cycle. Observe patterns, propose rule changes.
/update	Pull the latest Debriefs from GitHub.

The state machine

Every finding moves through states, tracked in frontmatter:

RAW → COMPILED → LINKED → VALIDATED → STALE → ARCHIVED

The state machine runs itself. Compile sets compiled. Lint promotes to linked when cross-links resolve. Staleness is flagged automatically. You only touch validated (when you've reviewed something) and archived (when it's no longer relevant).

Over time, /evolve watches the patterns — pages going stale too fast, pages stuck in compiled — and proposes rule changes. You approve or reject. The system gets sharper.

Team use

Each person gets their own debrief wiki. A collective repo synthesises across all of them — shared entities, cross-references, contradictions, team knowledge map.

Individual repos use folder-based access control:

raw/
  team/        ← shared with the collective (most research goes here)
  personal/    ← stays in your individual wiki only
  client-x/    ← quarantine for client proprietary data (their IP, not your research)

The distinction is whose IP is it, not which project you were working on. Research you do for a client is your knowledge — team/. Documents the client gave you with their proprietary data — client-x/.

The collective runs on a daily cron. It only reads team/ content. Client and personal material is structurally invisible to it.

Five rules that cannot be broken

1. Compiler reads only raw/ — never its own wiki output. Prevents fidelity decay.
2. Client data never reaches the collective — folder path = classification. Enforced by lint.
3. No large binaries in git — .gitattributes and pre-commit hook reject files >1MB.
4. Schema enforced by lint — every page must have required frontmatter. Lint failure = compile aborts.
5. Every compile is atomic — writes to temp, validates, then swaps. Wiki is never in a broken state.

Architecture

See ARCHITECTURE.md for the full technical design.

Browse with Obsidian

Your wiki is standard markdown with [[wikilinks]]. Open the repo folder in Obsidian for graph view, backlinks, and instant search. Obsidian is optional — the wiki works anywhere markdown renders.

Update

/update

Or manually:

cd ~/.claude/skills/debriefs && git pull && ./setup

License

MIT. See LICENSE.

Built by

A Player Labs. We build AI systems that give people leverage.