GitHub Copilot — Operating Manual

Start here

Four things to know before you touch a setting

1. The app is a place to run agents, not a chat window. The Copilot desktop app is built for agent-driven work: you can run several agent sessions at once, each on its own branch, and pick the model and the level of autonomy per session.

2. You are billed by tokens now, not by "requests." On 1 June 2026 every Copilot plan moved to usage-based billing with GitHub AI Credits. One credit is one cent. Every model has a published per-million-token rate for input, output, and cached tokens.

3. Inline code completions are still free. Completions and next-edit suggestions are not billed in credits on paid plans. Only chat, agents, CLI, code review and similar features draw down credits.

4. Model choice is the single biggest cost lever you control. Cheapest to priciest on the menu is roughly 40× on output tokens. Everything else in this manual is downstream of that one habit.

Watch the meter

How the money actually works

A token is roughly three quarters of a word. Everything the model reads is input tokens, everything it writes is output tokens, and repeated context can be cached at a lower rate. Output is always the expensive side — usually 5–6× the input rate.

Your plan comes with a monthly allowance of credits. When it runs out, additional usage bills at the same published rates if your organization allows it, or stops if a budget cap is set.

Plan	Monthly cost	Included AI credits	Notes
Pro	$10	$15	Unlimited completions; light chat and agent use.
Pro+	$39	$70	For heavy individual agent use.
Max	$100	$200	Only worth it if agents run for hours daily.
Business	$19 / user	$19 / user, pooled	Most corporate seats. Credits pool across the org.
Enterprise	$39 / user	$39 / user, pooled	Adds SSO and admin controls.

Find out what you're actually on

You are almost certainly on a company Business or Enterprise seat, so your credits come from a shared pool and your admin may have set a budget. Ask two questions before you build anything ambitious: what is our monthly credit budget per user, and is additional paid usage enabled or hard-capped? That answer sets the ceiling on how many scheduled agents you can responsibly run.

Pick a model

The cost dial

A shortlist of what you'll actually reach for, positioned by price per million output tokens — the number that moves your bill. Every model and every rate is in the Model catalog tab.

Output rate, $ per 1M tokens Log scale · GitHub published rates, Aug 2026

$10

$25

$50

GPT-5.6 Luna$1.20

GPT-5.4 nano$1.25

GPT-5 mini$2.00

Gemini 3.7 Flash$3.75

GPT-5.4 mini$4.50

Claude Haiku 4.5$5.00

Grok 4.6$6.00

Claude Sonnet 5$10.00

GPT-5.6 Terra$12.00

GPT-5.3-Codex$14.00

GPT-5.4 / 5.6 Sol$15.00

Claude Opus 5$25.00

GPT-5.5$30.00

Claude Fable 5$50.00

Input rates run roughly one fifth of output. Two promotions are live: GPT-5.6 Sol at half price through 3 Sep 2026, and Gemini 3.6 / 3.7 Flash at reduced rates through 31 Dec 2026.

Which one for which job

Your task	Use	Why
Tidy notes, rename files, reformat a table, quick "what does this mean"	GPT-5.6 Luna GPT-5.4 nano	Lightweight work at a fraction of a cent. Never spend a frontier model on formatting.
Draft a status update, summarize a meeting, write a first-pass email	GPT-5 mini Claude Haiku 4.5	Fast, competent prose. Good enough that you edit rather than rewrite.
Everyday agent runs: weekly digest, triage a list, follow a checklist	Claude Sonnet 5 GPT-5.6 Terra Grok 4.6	All three are classed as general-purpose coding and agent models. Your workhorse tier.
Reading a long document set and pulling out the through-line	Gemini 3.1 Pro	Built for long context and technical analysis. Watch the long-context tier above 200K input tokens.
Writing or fixing Python, DAX, M, SQL	GPT-5.3-Codex Claude Sonnet 5	Codex is tuned for agentic engineering work and lands complex changes without long instructions.
Hard thinking: a vendor comparison, an architecture call, a business case you'll defend	Claude Opus 5 GPT-5.6 Sol	Deep reasoning tier. Reach for it deliberately, on a fresh session, once you know what you're asking.
Long autonomous runs where you won't be watching	Claude Fable 5	Built for first-attempt correctness over long horizons. Also the fastest way to burn a month of credits — set a session limit first.
Not sure	Auto	Copilot routes to a suitable model and paid plans get a discount on model cost for using it. The correct default.

The habit that matters

Start on Auto or a cheap model. Escalate only when the answer disappoints you. Most people do the reverse — pin the most powerful model and leave it there for a month. Escalating costs you one re-run; defaulting high costs you every run.

Steer the session

Modes, effort, and knowing when to stop

Each session has three dials: the model, the reasoning effort, and the autonomy mode. The modes matter as much as the model.

Mode	What happens	Use it when
Quick chat	A conversation with no branch or workspace attached.	Scoping and questions. Cheapest way to think out loud.
Plan	The agent writes a plan and waits for approval before acting.	Anything unfamiliar or expensive. Catching a wrong plan costs one cheap turn.
Interactive	You and the agent work together, step by step.	Work where your judgment is part of the loop.
Autopilot	The agent runs to completion on its own.	Only for tasks you've already run manually and trust. Pair with a cheaper model and a credit limit.

Three moves that save real money

Start a fresh session when you switch tasks. Context carries forward and you pay to re-read it every turn.
Let agents run to completion. Inside a run, the tool calls the agent makes on its own are part of the run — it's your prompts that start the meter. Ten interruptions cost more than one good brief.
Run /chronicle cost tips weekly. The app will tell you where your own usage is expensive.

Set up the shop

Give yourself a workspace the agents can see

The Copilot app works on repositories — folders of files tracked by Git. It has no idea what your job is until something is written down in a folder it can read. So the first build is not an agent. It's a private repository that acts as your work brain.

work-brain/ — folder layout

work-brain/
├── AGENTS.md                  # who you are, how you want output written
├── context/
│   ├── portfolio.md           # your initiatives, one section each
│   ├── stakeholders.md        # who cares about what, and how they like it
│   └── glossary.md            # your company's acronyms and systems
├── inbox/                     # raw paste-ins: notes, exports, transcripts
├── log/                       # your running work record
├── briefs/                    # agent output: meeting prep, digests
└── .github/
    └── agents/                # your agent definitions live here
        ├── meeting-prep.agent.md
        ├── weekly-digest.agent.md
        └── intake.agent.md

The AGENTS.md file at the root is read by every agent, every session. Highest-leverage file you will write.

AGENTS.md

# Working context

I am a digital transformation advisor at an oil and gas operator.
My audience is a mix of operations leaders, engineers, and IT.
I am not a software engineer — explain technical choices in plain language.

## How to write for me
- Lead with the decision or the answer. No throat-clearing.
- Short paragraphs. Bullets only when the content is genuinely a list.
- Flag assumptions explicitly. If a source is missing, say so — never invent
  a number, a date, a name, or a system of record.
- Use our terms from context/glossary.md. Spell out an acronym on first use.

## Standing rules
- Never write anything to files outside this repository.
- Never include personal data, credentials, or anything marked confidential
  in generated output.
- When you summarize, cite the file in inbox/ or log/ you took it from.

## Files worth reading before you start
- context/portfolio.md — what I'm currently working on
- context/stakeholders.md — who I write for
- log/ — my running record, newest file is most relevant

Build the crew

Three agents that earn their keep

A custom agent is a markdown file with a short header. It gives Copilot a role, a limited set of tools, and a fixed model. Commit it to your default branch and it appears in the picker.

Restricting tools isn't fussiness — an agent that can't edit files can't wreck anything, and it costs less because it does less. The model line is how you stop a routine job from silently running on your most expensive model.

1. Intake — turns a mess into a usable note

.github/agents/intake.agent.md

---
name: intake
description: Cleans raw pasted notes, transcripts, and exports into a
  structured note filed under log/, with decisions and actions pulled out.
tools: ["read", "search", "edit"]
model: GPT-5 mini
---

You normalize raw material into a consistent note. You never editorialize
and you never add facts that are not in the source.

When given a file in inbox/:

1. Read it in full before writing anything.
2. Produce a new file in log/ named YYYY-MM-DD-slug.md with this structure:

   # <Title> — <date>
   **Source:** <inbox filename>  **Attendees / origin:** <if stated>

   ## What happened
   Three to six sentences of plain summary.

   ## Decisions
   - Decision — who made it — date if known

   ## Actions
   - [ ] Action — owner — due date if known

   ## Open questions
   - Question — who can answer it

   ## Unclear
   - Anything ambiguous in the source. Do not resolve it yourself.

3. Leave the original file in inbox/ untouched.

If a section has no content, write "None recorded." Never guess an owner
or a date.

2. Meeting prep — the one you'll use every day

.github/agents/meeting-prep.agent.md

---
name: meeting-prep
description: Builds a one-page prep brief for a specific upcoming meeting
  from the work log, the portfolio, and stakeholder notes.
tools: ["read", "search", "edit"]
model: Claude Sonnet 5
---

You prepare me to walk into a meeting without re-reading everything.

Ask for the meeting name and attendees if I have not given them. Then read
context/stakeholders.md, context/portfolio.md, and the three most recent
files in log/ that mention the same topic or people.

Write briefs/YYYY-MM-DD-<meeting-slug>.md, one page maximum:

## Where we left off
Three sentences. What was agreed last time and what has moved since.

## What each person walks in caring about
One line per attendee, drawn from stakeholders.md. If someone is not in
that file, say "no prior context on file" — do not speculate.

## What I owe them
Open commitments from log/ where I am the owner, with the date promised.

## What they owe me
Open commitments where someone else is the owner, and how overdue.

## Three questions worth asking
Specific to this meeting. Not generic.

## Risks I should be ready for
Only risks evidenced in the log. Name the file each one came from.

Hard rules: no filler, no restating the agenda back to me, every claim
traceable to a file. If the log is thin on this topic, say so in one line
at the top instead of padding the brief.

3. Weekly digest — the "what have I been doing" machine

.github/agents/weekly-digest.agent.md

---
name: weekly-digest
description: Compiles the week's log files into a status update written for
  leadership, plus a short private list of what slipped.
tools: ["read", "search", "edit"]
model: Claude Sonnet 5
---

You compile, you do not embellish.

Read every file in log/ dated within the last seven days, plus
context/portfolio.md for initiative names and framing.

Write briefs/YYYY-Www-digest.md with two clearly separated parts.

PART ONE — Send-ready update (aim for 250 words)
Written for an operations leader who has fifteen seconds. Organized by
initiative, not chronologically. Each item: what moved, what it unblocks,
what happens next. Outcomes, not activity. No adjectives.

PART TWO — For my eyes only
- Commitments I made that I have not delivered, with days elapsed
- Items that appeared two weeks running with no movement
- Anything I flagged as a risk that no one has picked up

Never invent progress. If an initiative had no activity this week, list it
under a short "No movement" heading rather than dressing up old news.

Where these files go

Easiest path: in the app or on GitHub, open the agents view and choose Create an agent — it scaffolds a file in .github/agents/. Rename it, paste the content, commit to your default branch, and it shows up in the dropdown. Creating the files by hand works the same.

Put it on a timer

Automations: the agent runs without you

An automation is a saved prompt with a trigger — hourly, daily, weekly, or on a repository event. In the app: Automations tab, then New automation. You set the name, prompt, trigger, allowed tools, and model. Tokens bill to whoever created it, so a badly scoped daily automation is a standing order against your credit pool.

Before it will work

The repository must be private or internal. Not available on public repos.
Copilot cloud agent must be enabled for that repository.
On a Business or Enterprise seat, an admin may need to enable it first.

Three worth setting up, in order

Automation 1 — Monday 07:00, weekly · model: Claude Sonnet 5

Using the weekly-digest agent, compile last week's log files into
briefs/ following the agent's format exactly. Open a pull request titled
"Weekly digest — week of <date>" so I can review it before it counts as
final. If fewer than two log files exist for the period, stop and open the
PR with a single line saying the log is empty for that week.

Automation 2 — daily 06:30 · model: GPT-5 mini

Check inbox/ for files added in the last 24 hours that have no matching
note in log/. For each one, run the intake agent to produce the structured
note. Do not modify anything already in log/. If inbox/ has nothing new,
do nothing and end the run.

Automation 3 — Friday 15:00, weekly · model: GPT-5 mini

Scan log/ for every unchecked action item where I am the owner. Produce
briefs/open-commitments.md as a single table: item, who I promised it to,
date promised, days elapsed, and the source file. Sort by days elapsed,
oldest first. Overwrite the previous version. Add no commentary.

Sequence, not enthusiasm

Run each by hand three or four times before scheduling it. You will rewrite the prompt every one of those times. A scheduled automation producing mediocre output isn't neutral — it costs credits weekly and trains you to ignore its output.

Work around the wall

Feeding it your work without connectors

No MCP connectors means Copilot cannot reach into your mail, calendar, Teams, or SharePoint. The honest framing is a division of labor:

Microsoft 365 Copilot is your retrieval layer. It already has sanctioned access to your mail, meetings, and documents. Use it to gather and summarize.
The GitHub Copilot app is your production layer. It holds your accumulated context, runs the agents, keeps history, does the scheduled work.

The bridge is a copy-paste habit that takes about ten minutes a week.

The Friday ritual

In M365 Copilot, ask for a summary of your meetings and mail for the week — decisions, commitments, open questions, with dates and owners.
Paste it into inbox/ as a dated markdown file. Raw is fine; that's what intake is for.
Add what M365 can't see: hallway conversations, your judgment calls, what you think is actually going on.
Run intake, then the digest. Read Part Two before Part One.

Prompt for M365 Copilot — weekly harvest

Summarize my meetings and email from the past 7 days as a plain markdown
list, grouped by topic rather than by day. For each topic give me:

- Decisions made, with who made them and the date
- Commitments, with the owner and the date promised
- Open questions and who can answer them
- Anything that changed from a previous week

Use only what's in my mail and meetings. Where something is ambiguous, say
so rather than resolving it. No summary paragraph, no recommendations —
just the structured list.

Check this before you paste anything

You're moving company content from one sanctioned system into another system's storage. In oil and gas that question has real answers attached — production data, JV terms, safety incidents, personal data, anything export-controlled.

Confirm with IT or security that storing work content in a private GitHub repo under your company's organization is approved. Get it in writing.
Use a repo owned by the company organization, not your personal account. Private or internal only.
Keep names, credentials, and identifiable personal data out of what you paste.
Ask whether content exclusion rules are configured for your org and whether they cover this repo.

If the answer is no, the approach still works on your own non-confidential material: your notes, plans, drafts, judgment. That's most of the value anyway.

Keep the meter honest

Cost discipline, condensed

Default to Auto; it routes sensibly and paid plans get a discount for using it.
Scope in a quick chat before opening a full session.
Use Plan mode for anything you haven't done before.
Pin a cheap model in every scheduled automation.
Start a new session per task.
Write one clear brief instead of ten corrections.
Set a credit limit on long autonomous sessions.
Run /chronicle cost tips every Friday.

Don't

Leave the most powerful model pinned as your default.
Run a frontier model on formatting or renaming.
Keep one giant session open all week.
Schedule an automation you haven't run manually several times.
Point a long-context model at a huge pile of files "just in case" — long-context tiers cost double.
Turn on automatic code review across repos without knowing the per-run cost.
Assume anything on this page is still accurate in three months.

A rough sense of scale

A meeting prep brief that reads ~15,000 tokens of context and writes ~1,200 tokens costs roughly 4 cents on Claude Sonnet 5 and roughly 9 cents on Claude Opus 5. Neither matters alone. Run it twice a day on the expensive model with a bloated session and you're at real money by month end — that's the actual failure mode. Use the estimator in the Model catalog tab to check your own numbers.

Four weeks

A ramp that doesn't overwhelm you

Learn the dials
Install the app. Do your normal work in quick chats only. Run the same question on a cheap model and an expensive one and notice where the difference actually shows up — for a lot of your work, it won't. Ask your admin about the credit budget.
Build the workspace
Create the private repo, write AGENTS.md and context/portfolio.md by hand. Paste a week of raw notes into inbox/. No agents yet.
Add two agents
Commit intake and meeting-prep. Run them manually before every meeting for a week. Edit the agent files as you go — fixing the prompt is the actual work.
Schedule the boring parts
Add weekly-digest. Schedule the two automations you've already proven by hand. Run /chronicle cost tips, look at your month's usage, decide what to cut. Then stop building and just use it.

Plain terms

Glossary

Token: A chunk of text, roughly ¾ of a word. Billing is measured in millions of them.
Context: Everything the model can see for one request: your prompt, the files it read, the conversation so far.
AI credit: GitHub's billing unit. One credit = one cent.
Repository (repo): A tracked folder of files. Your workspace and your agents both live in one.
Branch: A parallel copy of the folder where work happens safely before it's accepted.
Pull request (PR): A proposal to accept changes from a branch, with a review step. Your approval gate for agent output.
Agent: A model given a role, tools, and permission to act rather than just answer.
Custom agent: A markdown file in .github/agents/ defining one of those roles.
Automation: A saved agent task with a trigger, so it runs on a schedule or an event.
MCP: Model Context Protocol — the standard way to plug an AI tool into an outside system. Blocked at your company, hence the manual bridge.
Reasoning effort: A per-session dial for how much internal deliberation the model does. More effort, better hard answers, more output tokens.

Model	Class	Input	Cached in	Cache write	Output	Your run	Your month
OpenAI
GPT-5 mini	Lightweight	$0.250	$0.025	—	$2.00	$0.0061	$0.246
GPT-5.3-Codex	Powerful	$1.75	$0.175	—	$14.00	$0.043	$1.72
GPT-5.4 Long context >272K: 5.00 / 22.50	Versatile	$2.50	$0.250	—	$15.00	$0.055	$2.22
GPT-5.4 mini	Lightweight	$0.750	$0.075	—	$4.50	$0.017	$0.666
GPT-5.4 nano	Lightweight	$0.200	$0.020	—	$1.25	$0.0045	$0.180
GPT-5.5 Long context >272K: 10.00 / 45.00	Powerful	$5.00	$0.500	—	$30.00	$0.111	$4.44
GPT-5.6 Luna Long context >200K: 0.40 / 1.80	Lightweight	$0.200	$0.020	$0.250	$1.20	$0.0044	$0.178
GPT-5.6 Sol Promo −50% to 3 Sep 2026 · long >272K: 5.00 / 22.50	Powerful	$2.50	$0.250	$3.12	$15.00	$0.055	$2.22
GPT-5.6 Terra Long context >272K: 4.00 / 18.00	Versatile	$2.00	$0.200	$2.50	$12.00	$0.044	$1.78
Anthropic
Claude Haiku 4.5	Versatile	$1.00	$0.100	$1.25	$5.00	$0.021	$0.840
Claude Sonnet 4	Versatile	$3.00	$0.300	$3.75	$15.00	$0.063	$2.52
Claude Sonnet 4.5	Versatile	$3.00	$0.300	$3.75	$15.00	$0.063	$2.52
Claude Sonnet 4.6	Versatile	$3.00	$0.300	$3.75	$15.00	$0.063	$2.52
Claude Sonnet 5	Versatile	$2.00	$0.200	$2.50	$10.00	$0.042	$1.68
Claude Opus 4.5	Powerful	$5.00	$0.500	$6.25	$25.00	$0.105	$4.20
Claude Opus 4.6	Powerful	$5.00	$0.500	$6.25	$25.00	$0.105	$4.20
Claude Opus 4.7	Powerful	$5.00	$0.500	$6.25	$25.00	$0.105	$4.20
Claude Opus 4.8	Powerful	$5.00	$0.500	$6.25	$25.00	$0.105	$4.20
Claude Opus 5	Powerful	$5.00	$0.500	$6.25	$25.00	$0.105	$4.20
Claude Opus 4.8 fast mode Preview	Powerful	$10.00	$1.00	$12.50	$50.00	$0.210	$8.40
Claude Fable 5	Powerful	$10.00	$1.00	$12.50	$50.00	$0.210	$8.40
Google
Gemini 3.1 Pro Public preview · long >200K: 4.00 / 18.00	Powerful	$2.00	$0.200	—	$12.00	$0.044	$1.78
Gemini 3.5 Flash	Lightweight	$1.50	$0.150	—	$9.00	$0.033	$1.33
Gemini 3.6 Flash Promo rate to 31 Dec 2026	Versatile	$0.750	$0.075	—	$3.75	$0.016	$0.630
Gemini 3.7 Flash Promo rate to 31 Dec 2026	Versatile	$0.750	$0.075	—	$3.75	$0.016	$0.630
xAI
Grok 4.5 Long context >200K: 4.00 / 12.00	Versatile	$2.00	$0.500	—	$6.00	$0.037	$1.49
Grok 4.6 Long context >200K: 4.00 / 12.00	Versatile	$2.00	$0.500	—	$6.00	$0.037	$1.49
Microsoft
MAI-Code-1-Flash	Lightweight	$0.750	$0.075	—	$4.50	$0.017	$0.666
MAI-Code-1.1-Flash	Lightweight	$0.200	$0.020	—	$1.20	$0.0044	$0.178
GitHub
Raptor mini	Versatile	$0.250	$0.025	—	$2.00	$0.0061	$0.246
Moonshot AI
Kimi K2.7 Code	Versatile	$0.950	$0.190	—	$4.00	$0.019	$0.762
Kimi K3 See GitHub's model-specific safety note	Powerful	$3.00	$0.300	—	$15.00	$0.063	$2.52

Situation	Working model	Escalate to	Why this pair
Writing and summarizing all day	GPT-5 mini	Claude Sonnet 5	Ten-to-one cost gap, and mini handles most prose. Escalate when structure or nuance breaks down.
Scripting: Python, DAX, M, SQL	GPT-5.3-Codex	Claude Opus 5	Codex is tuned for engineering work. Escalate when a bug survives two attempts.
Scheduled automations	GPT-5 mini or GPT-5.6 Luna	—	Never escalate an unattended job. If it needs a better model, it needs your attention instead.
Thinking work you'll be judged on	Claude Opus 5 or GPT-5.6 Sol	—	Already the top. Control cost by scoping in a quick chat first, then opening one clean session.

The core idea

Two layers, and never confuse them

The instinct is to save everything into one pile. That fails twice over: it gets expensive to read (you pay tokens for every irrelevant file an agent opens) and it gets useless to search, because raw material buries the conclusions.

A memory bank that actually works has two layers with different rules.

Layer	What it is	Rule	Who writes it
The log	`log/` — dated notes, one per event. What happened, when, who said what.	Append-only. Never edited, never reorganized. It's evidence.	Intake agent, from raw material
The dossiers	`memory/projects/` — one living file per project. What it is, why you built it that way, how to demo it.	Rewritten continuously. Always reflects current truth, not history.	Scribe agent, from the log, reviewed by you

The log answers "what happened on 8 May." The dossier answers "what is this thing and how do I explain it." You need both, and the dossier is the one that saves you in four months.

On top of those sits a third thing that isn't really a layer — memory/INDEX.md, a single table of every project with a one-line description. It exists so an agent can read one small file to decide which dossiers are worth opening. That's the whole token-economics trick from Part two applied to your own memory: cheap map first, expensive territory second.

The test for whether a memory is worth keeping

Would you want to read this line in six months, in a conversation about something else? Decisions, constraints, results, and "why we rejected the other option" pass. Status updates, meeting logistics, and the fact that you had a call on Tuesday do not — those live in the log and expire there.

The shape

What gets added to the brain repo

This extends the work-brain layout from Part one. Everything new is under memory/.

work-brain/ — with the memory bank added

work-brain/
├── AGENTS.md
├── context/
│   ├── portfolio.md
│   ├── stakeholders.md
│   └── glossary.md
├── inbox/                     # raw paste-ins, cleared after processing
├── log/                       # append-only dated notes  (LAYER 1)
│   └── 2026-08-21-ops-sync.md
├── memory/                    # curated, living memory   (LAYER 2)
│   ├── INDEX.md               # the map — every project, one line each
│   ├── projects/
│   │   ├── anomaly-detection.md
│   │   ├── work-order-automation.md
│   │   └── historian-migration.md
│   ├── decisions/             # why you chose what you chose
│   │   └── 2026-05-02-adr-anomaly-baseline-method.md
│   ├── people/                # working context on recurring collaborators
│   └── archive/               # retired projects, compressed to one page
├── briefs/                    # agent output: prep, digests, deck outlines
└── .github/
    └── agents/
        ├── intake.agent.md
        ├── meeting-prep.agent.md
        ├── weekly-digest.agent.md
        ├── scribe.agent.md        # keeps dossiers current
        ├── recall.agent.md        # answers "what did I do about X"
        ├── archivist.agent.md     # monthly consolidation + pruning
        └── deck-builder.agent.md  # dossier to slide outline

The dossier template

Fixed structure matters more than good writing here. A consistent schema is what lets an agent reliably find the demo script four months from now. The front matter is machine-readable; the body is for you.

memory/projects/anomaly-detection.md

---
id: anomaly-detection
title: ESP pump anomaly detection prototype
status: shipped              # exploring | building | shipped | paused | retired
started: 2026-04-08
last_touched: 2026-08-14
tags: [python, time-series, reliability, pilot]
systems: [historian, power-bi]
stakeholders: [maintenance-superintendent, reliability-lead]
repos: [ops-anomaly-detector]
one_liner: Flags abnormal vibration patterns on ESP pumps roughly two weeks
  before failure, using historian tag data and a seasonal-decomposition baseline.
---

## Problem it solves
Two or three sentences. What was broken before this existed, and who felt it.

## What I built
Five bullets maximum, plain language. The version you would say out loud.

## How it works
The walkthrough, one step per stage: where data comes in, what transforms it,
where the output lands, who consumes it. Name the actual systems and tables.

## Key decisions
Link to the ADR files. One line each on what was chosen and what was rejected.

## Results
Numbers if you have them, with the date and the source. "Caught 3 of 4 failures
in the June pilot" is worth more in six months than any description.

## Demo script — 5 minutes
1. Open with the problem, in the audience's language
2. Show <the thing to show>, click <the thing to click>
3. The one slide or screen that lands the value
4. Known limits, stated before anyone asks
5. What it would take to scale it

## What broke / gotchas
The things you'd forget and get burned by. Data quality issues, edge cases,
the tag that's mislabelled in the historian.

## Open threads
What's unfinished and what would come next.

## Where things live
Repo, folder, dashboard URL, the notebook, who else has access.

The field that does the heavy lifting

Demo script. Write it while the project is fresh, even in rough form. It's the single hardest thing to reconstruct later and the exact thing you get asked for. Everything else in the dossier can be rebuilt from the log; this one is pure judgment that only exists in your head.

memory/INDEX.md

# Project index

Read this first. Open a dossier only if the one-liner matches the question.

| id | title | status | last touched | one-liner |
|---|---|---|---|---|
| anomaly-detection | ESP pump anomaly detection | shipped | 2026-08-14 | Flags abnormal vibration ~2 weeks before pump failure |
| work-order-automation | Work order intake automation | building | 2026-08-19 | Auto-routes SAP work orders by asset class and priority |
| historian-migration | Historian tag migration | paused | 2026-06-30 | Consolidating legacy tag naming into the new standard |

## Conventions
- id matches the filename in memory/projects/
- status: exploring | building | shipped | paused | retired
- retired projects move to memory/archive/ and drop off this table

Getting work in

Three intake streams

Memory only works if capture is nearly free. Three streams feed the log, and only one of them requires you to think.

Stream 1 — What your repos already know

Your commit history is an accurate, timestamped record of what you actually built, and you're already writing it. This PowerShell script pulls last week's commits from every repo on your machine into a single file in inbox/. Schedule it with Task Scheduler for Friday afternoon, or just run it.

tools/harvest-git.ps1

# Collects the past week's commits from every git repo under $Root
# into one dated file in work-brain/inbox/.

$Root      = "C:\repos"                        # where your repos live
$BrainRepo = "C:\repos\work-brain"
$Since     = (Get-Date).AddDays(-7).ToString("yyyy-MM-dd")
$Stamp     = Get-Date -Format "yyyy-MM-dd"
$OutFile   = Join-Path $BrainRepo "inbox\$Stamp-git-harvest.md"

"# Git activity since $Since" | Out-File $OutFile -Encoding utf8

Get-ChildItem -Path $Root -Directory | ForEach-Object {
    $repo = $_.FullName
    if (-not (Test-Path (Join-Path $repo ".git"))) { return }

    $log = git -C $repo log --since=$Since --pretty=format:"- %ad %s" --date=short
    if ([string]::IsNullOrWhiteSpace($log)) { return }

    $files = git -C $repo log --since=$Since --name-only --pretty=format:"" |
             Where-Object { $_ -ne "" } | Sort-Object -Unique | Select-Object -First 25

    Add-Content $OutFile ""
    Add-Content $OutFile "## $($_.Name)"
    Add-Content $OutFile $log
    Add-Content $OutFile ""
    Add-Content $OutFile "Files touched:"
    Add-Content $OutFile ($files | ForEach-Object { "  - $_" })
}

Write-Host "Wrote $OutFile"

Stream 2 — What Microsoft 365 knows

Same bridge as Part one, but pointed at memory rather than status. This prompt asks M365 Copilot for the things a dossier needs and a digest doesn't: decisions, reasoning, and commitments with their justification.

Prompt for M365 Copilot — weekly memory harvest

Review my meetings, chats, and email from the past 7 days. I'm building a
long-term record of my work, so I need substance rather than a status update.

For each distinct project or workstream, give me:

- The project name as people actually refer to it
- Decisions made this week, with WHO decided and WHY — include the reasoning
  given at the time, and any alternative that was rejected
- New constraints, requirements, or blockers that emerged
- Numbers, dates, or results that were quoted, with the source
- Commitments made, by me or to me, with dates
- Anything a newcomer would need explained to understand the discussion

Plain markdown, grouped by project. Quote directly where the exact wording of
a decision matters. If something is ambiguous, mark it "unclear" rather than
resolving it. Do not summarize into generalities — specifics are the point.

Stream 3 — What only you know

Ten minutes on Friday, in a plain file in inbox/. The reasoning you never wrote down anywhere, the thing you decided in the truck on the way back from the field, the hunch about why the pilot worked. This is the highest-value input and the only one that can't be automated. Answer four questions:

What did I figure out this week that I didn't know last week?
What did I decide, and what did I decide against?
What would I need to remember to demo or defend this later?
What's likely to bite me?

The crew, extended

Four more agents

These follow the same rules as Part one: restricted tools, a pinned model, and a fixed output shape. Note the model choices — the scribe and archivist are cheap, the recall agent is mid-tier because retrieval quality matters, and only the deck builder gets a strong model.

Scribe — keeps dossiers current

.github/agents/scribe.agent.md

---
name: scribe
description: Updates project dossiers in memory/projects/ from new entries in
  log/, preserving the template structure and never inventing detail.
tools: ["read", "search", "edit"]
model: Claude Sonnet 5
---

You maintain the project dossiers. You are a records clerk, not an author.

Process:
1. Read memory/INDEX.md to learn which projects exist.
2. Read log/ entries newer than each dossier's last_touched date.
3. For each project with new material, update its dossier in place:
   - Keep the exact section structure of the template. Never add or rename
     sections. Never reorder them.
   - Update last_touched and status in the front matter.
   - Add new facts to the right section. Do not restate what's already there
     in different words.
   - Where a new fact contradicts an old one, replace it and note the change
     in one line: "(was X, changed <date>)". History matters.
4. If material implies a significant choice was made, do not bury it in the
   dossier — create memory/decisions/YYYY-MM-DD-adr-<slug>.md instead, using
   the ADR format, and link it from the Key decisions section.
5. Update the row in memory/INDEX.md.
6. If a project appears in log/ that has no dossier, create one from the
   template with everything you can fill and "TBD" everywhere else.

Hard rules:
- Every fact traceable to a log file. Cite the filename inline.
- Never write the Demo script section yourself. If it's empty, add the line
  "TBD — needs 10 minutes from me" and list it in your PR description.
- Never touch log/. It is append-only.
- Open a pull request. Never commit to the default branch directly.

Recall — answers "what did I do about X"

.github/agents/recall.agent.md

---
name: recall
description: Answers questions about past work by reading the index first,
  then only the dossiers and log entries that are actually relevant.
tools: ["read", "search"]
model: Claude Sonnet 5
---

You answer questions about work I have already done. You have no edit access
and you never guess.

Retrieval order — follow it exactly, it controls cost:
1. Read memory/INDEX.md. Nothing else yet.
2. Pick at most three candidate projects based on the one-liners.
3. Read those dossiers. Stop if they answer the question.
4. Only if the dossier is thin, search log/ for the project id and read the
   three most relevant dated entries.
5. Only if still unresolved, widen the search.

Answering:
- Lead with the direct answer in two sentences.
- Then the supporting detail, in the order I would need it.
- Cite the file each claim came from, inline.
- State clearly what you could NOT find. "The dossier has no results section"
  is a useful answer. Inventing a plausible number is not.
- If the question is about something that predates the memory bank, say so
  rather than reconstructing it from thin evidence.

Deck builder — dossier to slide outline

.github/agents/deck-builder.agent.md

---
name: deck-builder
description: Turns a project dossier into a slide-by-slide deck outline
  pitched at a named audience.
tools: ["read", "search", "edit"]
model: Claude Opus 5
---

You turn a dossier into a deck outline. Ask who the audience is and how long
the slot is before you start. Those two answers change everything.

Read the project dossier and any ADRs it links. Do not read the whole log.

Write briefs/<project-id>-deck-<audience>.md. One block per slide:

  ### Slide N — <title as it appears on the slide>
  **On the slide:** the three to five words or the single visual. Not prose.
  **What I say:** two or three sentences, in my voice, plain language.
  **Source:** which dossier section this came from.

Rules for the deck itself:
- Open with the problem in the audience's language, never with architecture.
- One idea per slide. If a slide needs two claims, it's two slides.
- Technical depth scaled to the audience: operations leaders get outcomes and
  one diagram; engineers get the method and the failure modes.
- Include a limits slide before the ask. Stating your own constraints first
  is what makes the rest credible.
- Last slide is the ask, and it must be specific.
- Flag anything the dossier can't support with: "NEEDS INPUT — <what>".
  Never fill a results slide with invented numbers.

At the end, list the screenshots or exports I need to grab, with the exact
path or dashboard where each one lives.

Archivist — the cleanup crew

.github/agents/archivist.agent.md

---
name: archivist
description: Monthly consolidation. Compresses stale log entries, flags
  contradictions, and proposes retirements. Proposes only — never deletes.
tools: ["read", "search", "edit"]
model: GPT-5 mini
---

You keep the memory bank from rotting. You are conservative by default.

Monthly pass:
1. Log compression — for log/ files older than 90 days whose content is fully
   captured in a dossier, replace the body with a three-line summary and a
   pointer to the dossier. Keep the filename and the date. Never compress a
   file containing a decision that has no ADR.
2. Contradictions — list any place where two dossiers or a dossier and a log
   entry disagree on a fact, date, or number. Do not resolve them yourself.
3. Staleness — list dossiers with status building or exploring that have not
   been touched in 60 days, and ask whether they are actually paused.
4. Gaps — list shipped projects whose Demo script or Results section is empty.
5. Retirement candidates — projects untouched for 6 months. For each, propose
   a one-page compression into memory/archive/.

Output a single PR with the compressions applied and a description containing
the lists from steps 2 through 5 as checklists for me.

Absolute rules:
- Never delete a file. Compress, move, or flag only.
- Never delete an ADR or a Results section, at any age.
- Never resolve a contradiction. Surface it and let me decide.

On a timer

The rhythm

Four scheduled jobs, at four different cadences. Note that everything writes a pull request rather than committing — memory you never reviewed isn't memory, it's noise you'll distrust later.

When	What runs	Model	Your job
Daily 06:30	intake — clears `inbox/` into `log/`	GPT-5 mini	Nothing
Friday 15:00	Git harvest script, then your 10-minute brain dump	—	10 minutes
Monday 07:00	weekly-digest, then scribe updates dossiers	Claude Sonnet 5	Review the PR
1st of month	archivist — compress, flag, propose	GPT-5 mini	Work the checklist

Automation — Monday 07:15, weekly · model: Claude Sonnet 5

Run the scribe agent. Update every project dossier in memory/projects/ that
has new material in log/ since its last_touched date, then update
memory/INDEX.md to match.

Open a single pull request titled "Memory update — week of <date>". In the PR
description, list: which dossiers changed and why, any new ADRs created, any
project that appeared in the log without a dossier, and every section still
marked TBD that needs input from me.

If no dossier needs updating, do not open a PR.

Automation — 1st of month, monthly · model: GPT-5 mini

Run the archivist agent for the monthly pass. Apply log compression where the
rules allow it, and open one pull request titled "Memory maintenance — <month>".

The PR description must contain four checklists: contradictions found, stale
dossiers, shipped projects missing a demo script or results, and retirement
candidates. Apply no retirements yourself — I approve those individually.

Retention policy

Worth writing into memory/RETENTION.md so the archivist has a rule to follow rather than a judgment to make.

Content	Keep	Then
Decisions and their reasoning (ADRs)	Forever	Never compressed, never deleted
Results, numbers, outcomes	Forever	Never compressed
Project dossiers	Forever	Retired ones compress to one page in `archive/`
Demo scripts and gotchas	Forever	These are the whole point
Log entries	90 days full	Compress to 3 lines + pointer once captured in a dossier
Raw inbox files	Until processed	Delete once the log entry exists
Weekly digests	6 months	Delete — the underlying log and dossiers survive

Worked example

"Can you demo that anomaly tool you built?"

Four months on, no memory of the details, three days' notice. Here's the sequence end to end.

Ask recall what you built

Quick chat, recall agent: "What was the anomaly detection tool? What does it do, how does it work, and what were the results?" It reads INDEX.md, opens one dossier, and hands you back the answer with citations. Cost: under a cent. This is the moment the whole system pays for itself.
Check what's rotted

"What's stale or unverified in the anomaly-detection dossier? What would I get caught out on?" Four months is long enough for the data source to have moved or the pilot numbers to be superseded. Better to find that now than on the call.
Build the outline

Deck-builder agent: "Audience is the reliability team plus the ops superintendent. Twenty minutes with questions, so about eight slides. Goal is getting approval to extend the pilot to a second pad." It returns slide-by-slide with speaker notes, sourced to the dossier, plus a list of the screenshots you need and honest NEEDS INPUT flags where the record is thin.
Fill the gaps and generate

Grab the flagged screenshots, answer the NEEDS INPUT items. Then hand the outline to Copilot to generate the actual file — a python-pptx script in the app is the reliable route, or M365 Copilot in PowerPoint if your template lives there. Either way you're generating from a reviewed outline, not from a vague prompt, which is the difference between a usable deck and a generic one.
Feed the demo back in

Afterward, drop the questions you got asked into inbox/. Audience questions are the best possible input for the gotchas section — they're the gaps in your explanation, found for free. Next time the dossier is better.

Why this works and a folder of old files doesn't

Not because the AI is clever. Because four months ago you wrote down why you chose the seasonal-decomposition baseline and what the pilot caught, in a fixed place with a fixed shape. The agent is just retrieval. The memory bank is the part that has to exist.

Making it stick

Rules that keep it honest

Review every memory PR, even briefly. Unreviewed memory decays into confident nonsense.
Keep the log append-only. It's your evidence when a dossier and your recollection disagree.
Cite sources inside dossiers so any claim can be traced back.
Write the demo script while it's fresh, however rough.
Record what you rejected, not just what you chose.
Start with three projects, not your whole history.

Don't

Let an agent delete anything. Compress, archive, or flag.
Let the scribe write your demo script or invent results.
Backfill five years of history before the system has proven itself.
Store credentials, personal data, or anything confidential — same governance box as Part one, and it applies harder here because this is designed to persist.
Point a recall query at the whole repo. Index first, always.
Let dossiers and INDEX.md drift apart — that's what breaks retrieval.

Bootstrapping without the backlog

Don't try to reconstruct everything. Write dossiers for the two or three projects you're most likely to be asked about, from memory, in about twenty minutes each — TBD everywhere you can't recall. Then let the weekly rhythm fill in going forward. In three months you'll have a real bank; in a year you'll have something you'd genuinely miss.

One caution specific to memory

A memory bank is designed to outlive the context it was written in, which makes AI-generated inaccuracies far more dangerous here than in a throwaway summary. A wrong number in a status update is noticed that week. A wrong number in a dossier gets quoted confidently to a superintendent four months later. That's why every fact carries a citation, why the scribe can't write results, and why you review the PRs.

The operating manual

Four things to know before you touch a setting

How the money actually works

The cost dial

Which one for which job

Modes, effort, and knowing when to stop

Three moves that save real money

Give yourself a workspace the agents can see

Three agents that earn their keep

1. Intake — turns a mess into a usable note

2. Meeting prep — the one you'll use every day

3. Weekly digest — the "what have I been doing" machine

Automations: the agent runs without you

Three worth setting up, in order

Feeding it your work without connectors

The Friday ritual

Cost discipline, condensed

A rough sense of scale

A ramp that doesn't overwhelm you

Learn the dials

Build the workspace

Add two agents

Schedule the boring parts

Glossary

Model catalog

What a job costs, across the whole menu

Notes on the fine print

Long-context tiers

Cache write

Promotions running now

What isn't priced here

What your admin controls

Four default setups

Power BI design

Why AI-built reports come out looking like defaults

The five layers of an app-like report

Grid and canvas

Theme JSON — the highest-leverage hour you'll spend

The frame — background instead of borders

Navigation and state

Signature visuals

Injae Park's actual method

Start with these four files

A. Theme starter

B. SVG progress bar — in any table or matrix row

C. SVG delta indicator — arrow plus variance in one cell

D. Prompts that produce usable output

PBIR: your reports are now editable code

Twelve-point polish pass

Sources worth your time

The memory bank