# Context Stack Builder — Second Brain, Module 01

> Your Second Brain is a folder of context your AI wakes up knowing. Briefs, decisions, working
> memory, the people, the project state — wired in once, loaded in 60 seconds.

You are building it for the user, from files they already have. You are not writing a plan about
the files. **The deliverable is files on disk (Path A) or labeled markdown blocks they save
(Paths B/C), plus a debrief.**

**60-second daily load. 10-minute weekly reset. That's the whole practice.**

---

## The stack

| # | File | Changes | What it holds |
|---|---|---|---|
| 01 | `identity.md` | rarely | Who they are. How they want AI to answer. Their non-negotiables. |
| 02 | `project-<slug>.md` | weekly | One brief per active project. Goals, status, decisions, stakeholders, deadlines. |
| 03 | `state.md` | daily | What they touched today. What's blocked. What's next. This week's working memory. |

Three files. Built in ~10 minutes. Updated in 60 seconds a day. Everything else is optional bonus:

- **Wrappers (Path A only)** — `CLAUDE.md` and `AGENTS.md` at the project root tell filesystem
  agents to read the three files above on every session. Skip if the user is on Path B or C.
- **Patterns folder** — `patterns/` holds prompt templates and rubrics they've found work. Added
  over time, not now.
- **Artifacts** — code, docs, tickets **linked** from the project file. Never copy-pasted — the
  moment you copy, it goes stale.

---

## Step 1 · Pick the path (ask this first — it forks everything)

> "Where do you actually work with AI?"

| Path | Where | Tools | Prompt |
|---|---|---|---|
| **A** | On your computer — the agent reads a folder directly. Setup once; future sessions auto-load via the wrappers. | Claude Code, Cursor, Windsurf, Codex CLI, Aider, Copilot Agent, Gemini CLI | `references/path-a.md` |
| **B** | In a cloud Project — upload the three files once; the assistant remembers them across chats. | Claude Projects, ChatGPT Projects, Gemini Gems, Custom GPTs, NotebookLM, M365 Copilot | `references/path-b.md` |
| **C** | In any chat — attach files, paste the prompt, save the output. No setup, free tier works; you re-attach next session. | claude.ai, ChatGPT, Gemini app, Perplexity | `references/path-c.md` |

If you are running **inside** the user's repo or folder with write access, that is Path A — say so
and confirm, don't make them guess. Path A is the only path that writes files and the only path
that gets wrappers.

**Load the matching `references/path-{a,b,c}.md` and follow it.** It is the lesson's builder prompt,
carried near-verbatim. The steps below are the same method; the reference file is the source of
truth if they ever disagree.

---

## Step 2 · Gather context (do NOT ask them to write anything new)

They don't need to author documents. Point at **3–5 things they already work from**:

| Bucket | Examples |
|---|---|
| **Project context** | Brief, spec, or PRD · roadmap or strategy doc · slide deck for the work · stakeholder meeting notes · sprint retro or post-mortem |
| **Recent decisions & state** | Slack / Teams chat exports · email threads where decisions got made · last week's status update |
| **People & process** | Stakeholder list (who cares, who approves) · tickets (Jira / Linear / Asana) · SLA or scope documents |
| **Technical shape** *(when relevant)* | System diagrams, architecture sketches · DB schema or data dictionary · API contracts · runbook or ops playbook |

**The heuristic:** *pick the 3–5 documents that, if your AI had them open, would stop you having to
explain the project from scratch.* You don't need all of it.

Path A: they drop them in the folder. Path B: upload to the Project. Path C: attach in chat.

---

## Step 3 · Inventory **silently**

Scan. **Don't tell them what you found yet.** Triage:

- **High** — charters, briefs, PRDs, scope docs, meeting notes, decisions.
- **Medium** — PDFs, DOCX, PPTX (data-extract), exported chats.
- **Low** — filenames as weak signal.

**Skip secrets** — keys, passwords, tokens, `.env` files, anything marked confidential. If unsure,
skip and note it in the debrief.

---

## Step 4 · Ask 3–5 short questions — batched, once

**Batch in one message. Skip what the inventory already answered.** The battery:

1. My role.
2. How I want you to answer (direct/detailed/sparse, prose/bullets, push back or default-agree).
3. The one thing blocking or driving this week.
4. The last significant decision.
5. Who else is involved.

That is the whole interrogation. If the inventory already told you their role and the last decision,
ask three questions, not five.

---

## Step 5 · Draft the three files

Templates: `templates/identity.md`, `templates/project.md`, `templates/state.md`. Drafting rules —
these are the quality bar, not style advice:

- **Specific beats complete. 4 specific lines beats 20 generic.**
- **`[TBD: short reason]` when signal is weak. Don't invent.**
- **Recent-first in `state.md`** — today at top.
- **Honest status in `project-*.md`** — what actually works, not the roadmap.
- **identity.md Background: under 60 words.** One short paragraph — the operating experience that
  filters their decisions.
- **Artifacts are linked, never copy-pasted** — the moment you copy, it goes stale.
- Slug is lowercase: `project-feedrunner.md`.

### What "filled" looks like

This is the bar. Not headings with placeholders under them — filled fields, honest status, a real
`[TBD]` where the signal was weak.

```markdown
# Identity — Dana Osei
**Role:** Business analyst, Payments platform
**Focus:** Getting the FeedRunner reconciliation cutover approved before the Q3 freeze

## Background
Nine years in payments BA work, four of them on reconciliation. Has watched two cutovers slip
because nobody wrote the decisions down. Trusts a schema over a slide deck.

## Tools I use
- Claude Code, M365 Copilot, Jira, Confluence, DBeaver, Miro

## How I want you to answer
- Direct, bullets, no preamble. Push back when I'm wrong — don't default-agree.
- Cite the file path when you're working from one of my documents.

## Non-negotiables
- Never invent a stakeholder name, a date, or a ticket number.
- Never paste production data or customer records into a document.
- Say "I don't know" instead of guessing at reconciliation logic.
```

```markdown
# State — week of 2026-07-13

## This week
### Mon · 2026-07-13 — cutover paper, second draft
- Rewrote the rollback section after Priya flagged the 4-hour window as unfundable.
- Pulled the settlement-mismatch counts for June — 412, not the 90 the brief claims.

## Blocked
- **Cutover date** — can't finalise until Treasury confirms the freeze window. Waiting on Priya Raman.

## Next (priority order)
1. Send the corrected mismatch numbers to Priya before Thursday's steering call.
2. Get the rollback section reviewed by Marcus (DBA).
3. Update project-feedrunner.md status once the freeze window lands.

## Open threads (not blocking, not scheduled)
- Whether we retire the legacy nightly job in the same release or a follow-up.

## Decisions made this week
- Rollback is manual, not automated — the automated path can't meet the 4-hour window. (2026-07-13)
```

Note the shape: `state.md` is recent-first, blockers name a person, and "Next" is three specific
moves — not "continue work on cutover".

---

## Step 6 · Save

**Path A (writes to disk):**
- Create `context-stack/` if missing. Write the three context files into it.
- Write `CLAUDE.md` and `AGENTS.md` at the project root — **same content in both**, from
  `templates/wrapper-CLAUDE.md`. Substitute the real `project-<slug>.md` filename.
- **If any file already exists: don't overwrite silently. Show the diff and ask, OR write it as
  `<name>.new.md` for them to merge.**

**Paths B and C (no filesystem):** output three labeled markdown code blocks, one per file:

    ```markdown
    [file: identity.md]
    <contents>
    ```

Path B: they save those into the Project, which remembers them across chats. Path C: they save them
locally and drag them back in next session.

---

## Step 7 · Debrief — the debrief is the product

**Tell them what you couldn't do.** Path A shape (B/C variants are in their reference files):

```
## Context Stack built

**Created:**
- context-stack/identity.md          (24 lines, from: onboarding-notes.md + your answers)
- context-stack/project-feedrunner.md (41 lines, from: Q3-brief.pdf, retro-2026-06-30.md, jira-export.csv)
- context-stack/state.md             (19 lines, from: standup-notes.md + your answers)
- CLAUDE.md / AGENTS.md              (auto-loader wrappers)

**Files read:** Q3-brief.pdf, retro-2026-06-30.md, jira-export.csv, standup-notes.md, onboarding-notes.md
**Files skipped:** .env (credentials) · vendor-msa-signed.pdf (marked confidential)
**[TBD] markers:** project deadline — the brief predates the slip; confirm the new date and I'll fill it.

**Daily load:** open and ask "Where did I leave off?" — wrappers auto-load the three files.
**Weekly reset:** ~10 min updating each file + archiving last week's state.md.
```

---

## Optional · GitHub Copilot (VS Code) — a third activation surface

If their work happens in VS Code, Copilot can auto-load the Second Brain on every chat.
`.github/copilot-instructions.md` is attached to every Copilot Chat in the repo, by default.

1. **Enable** — VS Code › settings › search `github.copilot.chat.codeGeneration.useInstructionFiles`
   › enable. (On by default in newer Copilot Chat builds.)
2. **Reference** — create `.github/copilot-instructions.md` at the repo root:

   ```
   # Working with me

   You are pair-programming with [your name].

   ## Identity
   [paste identity.md]

   ## Current state
   See ./state.md for what I'm working
   on this week.

   ## Style
   [paste style.md or wrappers]
   ```
3. **Verify** — open Copilot Chat, ask *"What do you know about me?"* Copilot should answer with
   content from `identity.md`. If not, check the chat header — instructions files appear under
   "References" when active.

One source, three activation surfaces: Claude Code reads `CLAUDE.md`, agentic CLIs read `AGENTS.md`,
GitHub Copilot reads `.github/copilot-instructions.md`. For private second-brains, keep the repo
private; the instructions file never leaves the repo's read scope.

---

## Keep it fresh

The Second Brain is only as useful as `state.md`. Two habits:

- **Daily · ~60 sec** — open and ask *"Where did I leave off?"* Path A wrappers auto-load the three
  files. Path B/C: re-attach `state.md` at session start.
- **Monday · ~10 min** — Reset. Update each `project-*.md` with last week's decisions. Archive last
  week's `state.md`. Start a fresh one.

**The weekly reset is the user's job, not yours.** Don't offer to run it unattended.

---

## Hard rules

1. **Path A write scope, verbatim:** *Write only inside `context-stack/` and the wrapper files
   `CLAUDE.md` / `AGENTS.md` at the project root. Nothing else. Never modify or delete anything
   outside that scope.* Read only from the folder you were given access to. No traversal beyond.
2. **Never overwrite silently.** Existing file → show diff and ask, OR write `<name>.new.md`.
3. **Skip credentials** — keys, passwords, tokens, `.env`, anything marked confidential. If unsure,
   skip and note.
4. **Log every file you read and every file you write** in the debrief. No silent reads, no silent
   writes.
5. **Inventory silently.** The word is doing work — don't narrate the scan back at them before you
   ask your questions.
6. **Ask 3–5 questions, batched in one message.** Not an intake form, not one at a time.
7. **Don't invent.** Weak signal → `[TBD: short reason]`.
8. **Scaffold, don't solve.** You build a starting point; they refine it.
9. **Never copy artifacts into the project file** — link them.
10. **No wrappers on Paths B/C.** Wrappers are a Path A filesystem mechanism. Cloud Projects
    remember files by themselves.
11. **The 7-day staleness rule ships in the wrapper:** *If `state.md` was last updated more than 7
    days ago, flag it before answering — it may be stale.* Don't drop that line.

---

## Files in this skill

```
references/path-a.md          Path A builder prompt (filesystem write + wrappers)
references/path-b.md          Path B builder prompt (cloud Project, markdown blocks)
references/path-c.md          Path C builder prompt (any chat, markdown blocks)
templates/identity.md         who you are, how AI should answer, non-negotiables
templates/project.md          project-<slug>.md — brief, status, decisions, stakeholders
templates/state.md            this week's working memory
templates/wrapper-CLAUDE.md   the CLAUDE.md / AGENTS.md auto-loader (same content in both)
```

Source lesson: https://pickbits.ai/university/field-guides/01-second-brain/personal-knowledge-database
