Write a GLITCH.md for your project

GLITCH.md is a short file you commit to your repo that tells the AI report assistant what your product is and how things are done in it. The assistant reads it before it talks to anyone. When the answer is in the file, the person gets the answer and nothing is filed. When it is not, they get a better report — in your team's words.

The AI assistant cannot be switched on for a repo without one.

Where to put it

Commit it to the repo's default branch at any of these paths — the first one found wins:

1. GLITCH.md
2. glitch.md
3. .github/GLITCH.md
4. docs/GLITCH.md

What to write

Use headings; the assistant sorts each section by its heading. Keep the whole file to about a page.

# GLITCH.md

## What this product is
One or two sentences: what it does and who uses it.

## Roles
- **admin** — runs the firm, sees billing and every client.
- **staff** — works on assigned clients only.
- **client** — logs in to the portal to upload documents.

## Entities
- **engagement** — one piece of work for one client, with a due date.
- **proposal** — a quote sent to a client before an engagement.

## Areas
- **Clients** — the client list and each client's profile.
- **Billing** — invoices, payments, the reminders sent to clients.

## Guides and fixes
- **A client cannot log in.** Clients → the client → Portal access → Send invite again. The old link stops working.
- **An invoice shows the wrong GST.** The rate comes from the client's state: Clients → the client → edit State.

## Glossary
- "Assessee" means the client, in tax pages.

## Known limitations
- Bulk import accepts CSV only, not Excel.

## Don't report
- Anything on the public marketing site.

Which headings do what

Put it under a heading containing	The assistant uses it as
"what this product is", "about", "overview"	What the product is
"guide", "how to", "fix", "workaround", "steps", "FAQ"	Answers — the section that saves you reports
"role", "who", "persona"	Who the users are
"entities", "model", "data", "concept"	What your records are called
"area", "module", "section", "page"	The parts of the product
"glossary", "term", "naming"	Your words for things
"known", "limitation", "in progress"	Already known — it says so instead of treating it as news
"don't", "not report", "out of scope"	Things it tells people you don't track

Headings are matched in that order, so a heading like "Product areas" counts as what the product is, not areas. Name headings plainly.

Rules that keep it working

• Short beats complete. Only about the first 80 lines reach the assistant. The repo card warns tail cut when yours is longer.
• Guides and fixes is the section that pays. Each bullet is a report nobody has to write. Up to 3,000 characters of it are read; other sections up to 1,500 each. The whole file is capped at 24 KB.
• Use your team's words. If you call it "the executor", write "the executor" — the assistant will use it too.
• Longer how-tos belong in Guides. For anything more than two or three lines, write a guide on the Guides page and keep a one-line pointer here. Published guides are read by the assistant as well, and it can link to them.

After you commit it

• Turning AI ON on the repo card reads the file immediately.
• After an edit, the assistant picks up the new version within about 10 minutes.
• The repo card shows GLITCH.md · N guides — N is the number of bullet points under your guides section.

Keep it current

Press N unanswered on the repo card every week or two. It lists what reporters asked that neither this file nor your guides answered. Add a line under Guides and fixes for each, or write a guide, and the assistant answers it next time.

The GitHub App must be installed on the repo for Glitchgrab to read the file.