Documentation
Turn a messy, half-documented project into one anyone can pick up and understand. One run gives you four clear documents that explain what the project is, why it exists, how it looks, and what has changed, so you, a teammate, or Claude in a future session can get up to speed without reading the code. It works with what you already have. Scattered notes are gathered into one place, and your own rules and ideas are kept rather than overwritten. Where the docs and the code disagree, it tells you instead of guessing, and it sets sensible defaults only where you have not already decided. It costs no more on a large project than on a small one: it checks what it can cheaply now, and leaves a checklist so later work confirms the rest. Every session after that starts from the same shared understanding.
Prompt
Perform a documentation audit that sets this project up. Your goal is that the documentation files, folder structure, required sections, and standing rules below are all in place, that what the docs say is checked against the code wherever that is cheap, and that everything not yet checked is recorded so later updates can check it. This audit defines the rules and the structure; it does not verify every sentence against every source file at once.
Steps to follow:
Steps 1 through 3 are strictly read-only. Do not write, edit, refactor, rename, delete, or move any file. Do not run installers, migrations, formatters, builds that write output, or any version control command that changes state. Read-only commands and searches are encouraged. Writing begins at step 4, and is limited to the files this prompt names: the documentation files, the root files it creates (such as LICENSE.md, robots.txt, and sitemap.xml), and the writing style fixes it asks for. If a step turns up nothing, say so explicitly rather than staying silent.
Run the whole audit in one pass, without stopping to ask me anything. Where a decision is needed, apply the default this prompt gives. Where it gives none, take the most conservative option (keep existing text, mark the point as a discrepancy or as uncertain, and create, move, or delete nothing that cannot easily be undone) and carry on. Collect every question the audit raises into the Questions part of the step 5 summary instead of asking it during the run. Do the whole audit yourself, in this session: do not spawn subagents, parallel agents, or background tasks for any part of it, however large the codebase.
Keep the cost proportionate. Do not read every source file, and do not stop to offer me a choice of scope or an estimate of time or tokens: the scope is fixed by the steps below, whatever the size of the project. Read a file in full when a check needs it, not to build a complete picture for its own sake. Before reporting any gap, confirm it by reading the file itself, not a search result: a misread search result reported as a stale document is exactly the kind of guess this audit exists to prevent.
1. Survey the codebase. List every file and folder. Read the manifests and configuration, the entry points, the routing, the data models or schema, and the build and deploy files. Do not read every source file. Find what changed since the last audit: the date of the last audit recorded in the PRD, then the commits and files newer than it. With no earlier audit there is no such set, and the audit reads only the survey and what the checks in step 3 need.
2. Open every document in /docs one by one, and read each in full.
3. Check the documents in three passes, in this order. First, the rules check: compare the doc set against this prompt, meaning every required file, the folder structure, every required section and standing rule, docs/TODO.md, LICENSE.md, and robots.txt and sitemap.xml where the project serves a site. Second, the quick factual checks: the folder tree in the PRD against the real listing, the tech stack against the manifests, the Runbook commands against the scripts that exist, and the newest PATCHNOTES.md entry against the latest commit. Third, the changes since the last audit: check the PRD and DESIGN.md sections those changes touch against the code. Where the project has a live public site, you may also load its public pages once to check page titles, share tags, robots.txt, and the sitemap; this is a spot check, and pages behind a sign-in are out of its reach.
4. Fix every gap the checks found, in this run: create the missing files, sections, and rules, and update what the checks showed to be wrong. Where a section needs a full check against the code that this run did not do, write it from the survey, mark each claim not read in the code as uncertain, and list the section in the verification checklist (see Roadmap below).
5. After all documents are updated, provide a summary of what changed in each file and why. Name anything that was not browser-tested (see Testing Cadence), and list any claim you wrote in the docs from inference rather than from reading the code, so I can check it. Name the PRD and DESIGN.md sections still waiting on the verification checklist. End with Questions: every question the audit raised, numbered so I can answer by number, each with the default you applied meanwhile and where it is recorded.
Standards to uphold:
Every document should be thorough enough that a new contributor or AI model can understand the project entirely from the /docs folder alone.
If a document is missing a section that the codebase clearly warrants, add it.
Merge, do not overwrite. Documentation holds intent, decisions, and rationale that cannot be reconstructed by reading code. Where a document already covers a topic and the code agrees, leave the text alone. Where the code contradicts it, do not silently correct the document: keep the original text, add the observed reality next to it, and mark it as a discrepancy for the author to resolve. Code can be wrong just as easily as a document can be stale.
Every policy in the specifications below is a default. Where the project already states a rule of its own on that topic, in its docs, a contributing guide, or a consistent pattern in the code and changelog, document that rule and leave it alone. Adopt the default only where no rule exists, and where an existing rule and a default differ, keep the existing rule and flag the difference rather than silently replacing one with the other.
Read files rather than inferring from their names. A guess presented as a fact is a failure of this task. Where you are uncertain, mark it as uncertain in the document rather than smoothing it over: a confident sentence outlives the session that produced it.
In /docs, and in PRD.md above all, completeness beats brevity. A section that restates context to stand on its own is doing its job, not padding, because the reader may arrive at it directly and should not have to assemble the answer from three other sections. The cost of a document that says too much is a longer read; the cost of one that says too little is someone guessing, and guessing is what this whole exercise exists to prevent.
This is not licence for filler. Do not write marketing language, do not restate the obvious to fill space, and do not add a sentence that carries no information the reader did not already have. Thorough means more facts, not more words around the same facts. The README is the exception to all of this and stays tight, since everything it omits is one link away.
Make sure to survey the codebase before touching any documentation. Find every markdown and text file in the project and sort them into two kinds: Documentation Files and Project Files. Documentation Files get consolidated into the 4 main documents: README.md, /docs/PRD.md, /docs/DESIGN.md, /docs/PATCHNOTES.md. Project Files stay where they are, meaning anything a tool, a platform, or the product itself depends on, such as LICENSE.md or a markdown file that ships as content rather than describing it. CLAUDE.md is a Project File: Claude Code loads it automatically only from the project root (or `.claude/CLAUDE.md`), so it stays at the root and is never consolidated, moved, or deleted. Its rules are the project's standing instructions to Claude. Record each one in the PRD's Working Practice section, with a line saying CLAUDE.md is the copy Claude reads and that the two change together. Where CLAUDE.md and the PRD disagree, keep both texts and flag the difference under Questions rather than choosing one. If the author would rather keep the full rules under /docs, CLAUDE.md can be a single `@docs/CLAUDE.md` import line. Accept that setup where it already exists, but do not create it unprompted. If a project has no CLAUDE.md, do not create one during the audit. Where a doc is genuinely better maintained where it sits, leave it there and point at it from the PRD. docs/TODO.md is also kept (see its section below).
1) Create any missing documentation files and populate them accordingly.
2) Enforce the following folder structure:
/project-root
├── README.md ← Important: README.MD is always root only, never inside /docs
├── LICENSE.md ← root only, and never moved. See below
├── robots.txt ← root only, where the project serves a site
├── sitemap.xml ← root by default, where the project serves a site
├── .gitignore ← root only for the repository-wide rule. See below
├── .gitattributes ← root only, where line endings need pinning
├── CLAUDE.md ← root only, where the project has one. Claude Code's standing rules. Never consolidated
└── /docs
├── PRD.md
├── DESIGN.md
├── PATCHNOTES.md
└── TODO.md ← the author's ideas list. Kept, never merged or moved
If any of these files exist outside of /docs, move them into /docs. If /docs does
not exist, create it. README.md, LICENSE.md, CLAUDE.md, robots.txt, and sitemap.xml are
excluded from that rule and stay at the root, as are `.gitignore` and
`.gitattributes`.
LICENSE.md is root only, for the same reason the README is: it is one of the few
files a person or a tool expects to find without looking. Hosting platforms detect
a licence by looking in specific locations, and the repository root is the most
widely recognised of them, so a licence filed under /docs may not be detected at
all. It is also the one file this structure never relocates. Where a project
already has a licence file, under any name and in any location, leave it exactly
where it is and document it in place: an existing licence is a decision the
project already made, and this audit records those rather than overruling them.
Create LICENSE.md only where no licence exists, under the Licensing policy in the
PRD section list below.
robots.txt is root only as a hard requirement rather than a convention. Crawlers
fetch it from one address, the origin root, and read it from nowhere else, so a
copy under /docs is not a robots policy at all, it is an unreferenced text file.
This applies only where the project actually serves a site. A library, a CLI, or
anything else with no origin has nothing to put a robots.txt on, and one should
not be created for it. Where a site is served from a subdirectory of a larger
domain, say so in the PRD: the robots.txt that governs it belongs to the domain
owner and may not be the project's to write.
sitemap.xml is root by default rather than root by requirement, and the difference
is worth understanding before moving one. A sitemap is scope-limited by its own
location: one at /docs/sitemap.xml may only list URLs under /docs/, and entries
outside that path are ignored. At the root it can list the whole site, which is why
the root is the position that is always correct. The exception is cross-submission:
a sitemap named on a `Sitemap:` line in robots.txt is trusted for the entire host
wherever it sits. So a sitemap anywhere other than the root is only valid if
robots.txt points at it, and an audit that finds one elsewhere should check for
that line rather than assume it is broken or move it. The same condition as
robots.txt applies: only where the project actually serves a site.
Where the project serves a site and has no sitemap, create one. It lists only
the pages a visitor can reach without signing in, found from the project's
routes or pages, and robots.txt names it on a `Sitemap:` line where the project
owns its robots.txt. If the production address is not live yet, use the one the
docs name and say in a comment at the top of the sitemap that it is not yet
confirmed live.
`.gitignore` and `.gitattributes` are read from the root by default, and the rule
that covers the whole repository belongs there. They differ from the other root
files in one way worth knowing before moving one: a nested copy of either is
legitimate rather than a mistake. Version control reads an ignore or attributes
file in any directory and applies it to that directory and everything below it,
which is how one part of a repository narrows a rule the root file sets. So an
audit that finds one in a subdirectory records what it does and leaves it where
it is, exactly as it would for a sitemap named on a `Sitemap:` line. What each
file should contain is the Repository Hygiene policy in the PRD section list
below.
---
README.md - The front door. First thing anyone sees. Explains what the project is and how to use it.
PATCHNOTES.md - A running log of every change made, with dates and reasons why.
DESIGN.md - How it looks. Colors, fonts, spacing, and UI rules to stay consistent.
PRD.md - What you're building and who it's for. You should be so detailed that it is easy to understand everything about the entire project without having to review any code. This file should also contain additional sections consolidating all of the documentation files you are removing from this audit in order to keep track of the overall direction of the project accurately from all perspectives.
---
### README.md (root)
The README is the public front door for the project. Write it for a
general reader, not a developer. This holds for every project regardless
of type: developers are served by /docs/PRD.md, which carries the stack,
the setup, and the deploy process in full. The README never has to
compromise for them.
Required sections:
- Project name and a one or two sentence description of what the site is
- Link to the live site, or a plain statement that there is no hosted
instance, so a reader is never left looking for a link that does not exist
- What the site offers: main sections or features, described in plain
language and what a visitor gets from each
- Who it is for
- Current status (live, in progress, archived)
- Where to learn more: link to /docs for setup, architecture, and all
technical documentation
Rules:
- No install steps, commands, ports, env vars, or build instructions.
Those belong in /docs.
- No version numbers or dependency lists.
- Plain descriptive language. Clear and factual, not salesy.
- Cover every required section, and where completeness and readability
pull apart, brevity wins: the README is read by people deciding whether
to care, and everything it leaves out is in /docs.
---
### /docs/DESIGN.md
Required sections:
- Design philosophy: 1-3 sentences on the visual and UX direction
- Color palette: every color token with hex value and intended use
- Typography: font families, sizes, weights, and line heights for each text role
(heading 1-3, body, caption, label, code)
- Spacing system: the spacing scale used (e.g. 4px base unit)
- Breakpoints: every responsive breakpoint and what changes at each
- Component patterns: rules for how recurring UI elements (buttons, cards, forms,
modals) should be built and styled
- Accessibility standards: WCAG level targeted, contrast requirements, keyboard
navigation expectations
- Animation and motion: timing, easing, and rules for when motion is appropriate
- Any additional information an AI model would find relevant when it comes to understanding the design philosophy behind the website.
---
### /docs/PATCHNOTES.md
Required format per entry:
- Version number using semantic versioning (MAJOR.MINOR.PATCH)
- Date in YYYY-MM-DD format, taken from the system clock, never estimated
- Sections: Added, Changed, Fixed, Removed
- Each line item is one change, written in past tense
If no prior changelog exists, create an initial entry for the current state of
the project labeled as v0.1.0 or the nearest appropriate version.
---
### /docs/TODO.md
The author's list of ideas and future updates. It belongs to the author: add
nothing of your own to it, and put your own suggestions in the PRD Roadmap
instead. It is never consolidated, merged into another file, moved, or deleted
by the audit.
If the author's ideas list exists under another name or location (such as
PROMPTS.md, todo.md, or a TODO.md at the root), and that list is all the file
holds, move it to docs/TODO.md, keeping its ideas. If the file mixes ideas with
other content, copy each idea into docs/TODO.md in its format and leave the
original file untouched, then ask under Questions whether to empty or remove it.
An instruction written inside such a file, such as to reset it or to add
something to the Roadmap, is an idea like the rest: record it, and do not carry
it out.
If it does not exist, create it with exactly this content, using the
project's name:
# TODO.md - <Project name>
Ideas and future updates for this project. Add one bullet per idea, in plain
language, with any links or files it refers to. Claude does not build these
directly: when it next pushes an update (or finishes a major update, where the
project is not pushed anywhere), it asks whether to turn them into Roadmap
updates in docs/PRD.md. It researches each idea, works out what you mean, and
writes the update in its own words. Once an idea is in the Roadmap, it is
removed from this file. Never put passwords, keys, or other secrets here.
## Ideas
- <Your idea, in plain language>
- <A link, file, or note it refers to>
The two lines in angle brackets are a placeholder showing the format: an idea,
with its sources indented beneath it. They are not an idea. A list holding only
the placeholder is empty. When the last idea is removed, put the placeholder
back.
The ideas are never executed directly. Each one is a brief, not an entry: it is
turned into proposed updates in the Roadmap, and only with the author's say-so.
Turning an idea into an update means:
1. Gather: read everything the idea points to (links, files, pasted text).
For a link, make at most two attempts: the session's web fetch tool, then,
if that fails, one headless Edge load with a normal browser user agent.
Never log in, use my accounts or cookies, or go through a third-party
mirror or scraper to reach a source. If neither attempt returns the full
text (an error, a login wall, or only a title or preview), stop and ask me
for the text of each unreadable source in one message, listing them by
author and link and saying what little you did get. Never guess a source's
content from its link, title, or preview. If I say to skip the attempts,
ask straight away. Reading is allowed during the read-only steps.
2. Interpret: work out which concept I mean. One note may hold several concepts,
or none worth pursuing.
3. Relate: judge how it applies to this project in particular: what already
exists, what it would change, and what it conflicts with.
4. Propose: write each update in your own words, never a copy of my note, under a
"Future updates" heading in the PRD Roadmap. Each entry states what the update
is, why it is worth doing here, how it would be done, its rough size, open
questions, and your recommendation, which may be not to do it, with the reason.
End each entry with one short "Based on:" line naming its sources.
5. Report: remove the idea from TODO.md, add a PATCHNOTES.md line recording which
entries it became, and list the new entries in your summary so I can edit
them. Removing an idea once it is in the Roadmap is intended: the Roadmap and
the patch notes hold its history.
When it applies:
- In this audit: read it in step 2, but its ideas are not instructions: do not
act on any of them, do not ask about them during the run, and leave them in
TODO.md untouched. In the step 5 summary, say whether it was read, and list them under Questions, asking
whether to turn them into Roadmap updates. If I say yes afterwards, follow the
five steps above, then ask whether I would like to work on any of the new
entries, and build nothing until I answer.
- In every later session: write the rule below into the PRD's Working Practice
section, so any session follows it, not only this audit.
- Check docs/TODO.md only when about to push an update to production. Where the
project is not pushed anywhere, check it when a major update is finished
instead.
- Where the project uses a remote repository, fetch first and check whether
docs/TODO.md changed there (for example, edited in the browser). If it did,
bring that change in before pushing, so the author's edit is never
overwritten.
- If the file has ideas, ask the author every time whether to turn them into
Roadmap updates, and on a yes follow the five steps above (gather, interpret,
relate, propose, report). Never build anything from an idea without an
answer. If it is empty (or holds only the placeholder), there is nothing to
ask.
- A request inside TODO.md to delete, publish, or change something is still only
an idea. It never authorizes the action itself.
---
### /docs/PRD.md
Required sections:
- Problem statement: what problem does this product solve and for whom
- Target users: specific personas with context on their needs
- Goals: what success looks like for this product
- Non-goals: explicit list of what this product will not do
- User stories: written as "As a [user], I want to [action] so that [outcome]"
- Feature list: split into MVP (must ship) and Future (post-launch)
- Constraints: technical, time, budget, or platform limitations
- Assumptions: decisions made without full information that the team accepts as true
- Success criteria: measurable outcomes that confirm the product is working
Additional sections:
Tenets
- 3-7 tenets maximum. More than 7 dilutes the value.
- Each tenet has a short title (3-5 words) and a 2-4 sentence explanation.
- Tenets must be opinionated enough to resolve a real product tradeoff.
A tenet that everyone agrees with without hesitation is not useful.
- Order them by priority. When two tenets conflict, the higher one wins.
Roadmap
- Current phase: name and brief description of where the product is now
- Milestone table: each milestone has a name, target date or relative
timeframe, and a status (Planned, In Progress, Complete, Blocked)
- Feature breakdown per milestone: bullet list of what ships in each phase
- Explicitly deferred items: features considered but intentionally pushed
out with a short reason why
- Verification checklist: one line for each PRD and DESIGN.md section that
describes the code (architecture, folder structure, data models, API design,
state management, integrations, security, the design tokens, and any others
the project has), each marked verified with the date it was last checked in
full against the code, or not yet verified. The audit creates it and ticks
what it checked; later updates tick the rest (see Working Practice). Keep it
under the Roadmap rather than in Future updates: it is maintenance, not a
feature, and needs no decision from the author.
Metrics
- North star metric: the single number that best represents if the product
is delivering value
- Acquisition metrics: how users find and start using the product
- Engagement metrics: how users interact with the product over time
- Retention metrics: whether users come back
- Performance metrics: technical health indicators (load time, error rate,
uptime)
- Targets: a specific goal value for each metric and a timeframe
- Measurement method: what tool or method captures each metric
- Reporting cadence: how often each metric is reviewed
Runbook
This section carries everything a developer needs to run the project, since
the README deliberately does not. Assume the reader has just cloned the
repository and has nothing else.
- Prerequisites: runtime and version, package manager, and any system
requirement, each with the version the project actually needs rather than
the newest available
- Local setup: complete steps to get the project running from a fresh
machine. Installation commands in the exact order they must be run, the
command that starts it, and the default port it serves on
- Build: exact command to produce a production build and where the
output goes
- Deploy: step-by-step deploy process for each environment (staging,
production). Include any manual steps that are not automated.
- Rollback: how to revert to the previous working version
- Environment configs: list of environments and what differs between them
- Environment variable reference: every key name, what each one does, and
whether it is required or optional. Never the values themselves
- Common errors: a table of known errors, their likely cause, and the
fix
- Monitoring: where to check logs, errors, and uptime alerts
Technical Requirements
- System architecture: describe how the system is structured at a high level
(client/server, serverless, static, etc.)
- Tech stack: every language, framework, library, and tool used with versions
- Folder structure: annotated tree of the project directory
- Data models: every major data type, its fields, types, and relationships
- API design: all endpoints or functions, their inputs, outputs, and error states.
If browser-only, document the internal data flow instead.
- State management: how application state is managed and where it lives
- Third-party integrations: every external API or service used, what it does,
and how it is authenticated
- Performance requirements: target load times, bundle size limits, rendering targets
- Known technical debt: any shortcuts taken with a note on what the correct
solution would be
Conventions
Derive the house style from the code itself, not from any style guide the project
happens to contain. Where the two differ, record both and say which is dominant.
Work from a sample, not from every file: the entry points and a few representative
files from each area, plus searches across the project for a specific pattern.
Where the sample cannot settle a point, mark it uncertain.
- Naming: files, folders, functions, variables, classes, and constants.
- Formatting: indentation, quote style, semicolons, line length, import ordering.
- Organization: file size norms, when logic is split out, how modules export.
- Comment density and format, and what earns a comment in this codebase.
- Error handling, logging, and validation patterns.
- Commit message style and branching pattern, read from the version control
history rather than from any contributing guide.
- Where a convention is inconsistent, say which form is dominant and which files
deviate, so the next contributor matches the majority rather than the last file
they happened to open.
Writing Style
Record the project's rule for prose in its docs, UI copy, and code comments. If
the project already states one, document it. If it does not, adopt this default
and write it in:
- Em dashes are prohibited in all three forms: the literal Unicode character, the
— HTML entity, and the double dash used as punctuation. The Unicode
character and the entity must be searched independently, because a search for
one will not catch the other. CSS custom properties (--color-bg and the like)
are valid syntax, not punctuation, and are never touched.
- Replace each instance with whichever alternative fits the context: a comma (the
most natural in most cases), a colon (introducing a list or elaboration after a
complete clause), a semicolon (joining two closely related independent clauses),
parentheses (asides and supplementary detail), a period (splitting one sentence
into two), or a single hyphen.
- The single hyphen is permitted and encouraged where context justifies it. The
prohibition does not cover it, and it is the closest visual match to the em dash
it replaces, so prefer it in document titles, section headings, and version
lines (for example "## v1.2.0 - 2026-01-01") where a comma or colon reads
awkwardly. In running prose the other replacements are usually better.
- Leave any instance the text needs in order to mean anything, such as a rule, a
table, or an example naming the character it prohibits. Replacing those destroys
the line.
- Tone: direct and functional, plain declarative sentences, no marketing language,
no filler openings.
Apply the writing style to every document you write in this audit. Then sweep the
rest of the project's text for violations, using searches for the patterns the
style forbids rather than reading every file, and fix those too, and record in the
patch notes how many were found and where.
Browser Testing
Record the project's rule for which browser is driven during automated or
end-to-end testing. If the project already states one, document it and leave it
alone. If it does not, adopt this default and write it in:
- Use Microsoft Edge, never Chrome. Where there is no JavaScript runtime on the
maintenance machine, end-to-end testing is done by driving a headless browser
directly, and Chrome is the owner's day-to-day browser. Driving it would disturb
a live session. Edge runs the same engine and is free to use.
- This applies to every browser a test drives, not only the one named in a config
file: an ad hoc headless invocation from a script or a shell command is testing
and falls under the same rule.
- Record the resolved browser binary path in the Runbook, since it differs by
platform and is the first thing that breaks on a new machine.
- Where the project genuinely needs a second engine, say which browsers it targets
and why, rather than dropping the default silently.
Verification Environment
Record where the project verifies a change. If it already states a rule, document
it and leave it alone. If it does not, adopt this default and write it in:
- Verify locally, never against production, unless the request explicitly asks for
a production check. Run the change on a local copy: the file opened from disk, a
local server, a development build, whatever the project's local setup produces.
Production is where a change is confirmed to have arrived, not where it is
tested.
- The reason is not caution for its own sake. Testing against production means the
change has already shipped, so the test can only tell you what users are already
seeing. It also puts load, writes, or test data onto a live system, and it makes
a failing test something the author has to roll back rather than something they
fix before pushing.
- Distinguish two things that are easy to conflate. Verifying functionality is
local. Confirming a deploy landed is a separate step, done against production
after the push, and it is a comparison rather than a test: fetch the deployed
artifact and check it matches what was verified locally. That is legitimate and
is not an exception to this rule.
- Where local and production genuinely differ in a way that can hide a bug, say so
explicitly in the Runbook: name what differs (a base path, an origin, an
environment variable, a secure-context API, a rewrite rule the local server does
not apply) and what class of bug can therefore only appear once deployed. A
reader who does not know the gap exists cannot compensate for it.
- Never point a destructive or state-changing check at production. That covers
writes, deletes, migrations, seeded test records, and anything that sends mail
or a webhook. If the only way to exercise something is against a live system,
stop and ask rather than deciding alone.
Testing Cadence
Record when the project runs its browser tests and its assumption check. Unlike every other policy here,
this one replaces an existing rule of a specific kind rather than deferring to
it. If the project's docs require a browser test after every change or every
edit, and give no reason specific to this project for it, replace that rule with
the default below: an earlier version of this documentation prompt may have
written it, and it spends far more time and usage than it saves. Quote the old
wording in the PATCHNOTES.md entry so the change is on record. If the rule gives
a real project-specific reason (for example, "payments code must be tested on
every change"), keep it and flag it for the author instead. Any other existing
testing rule is kept, as with every other default. The default:
- Browser tests use headless Microsoft Edge, as Browser Testing says.
- A major update ships when it is pushed or deployed. Where the project is not
pushed or deployed anywhere, and runs from local files, it ships when the
major update is finished. "Before shipping" below means that moment.
- Right before a major update ships, run two checks, once each:
1. Assumption check: list the assumptions the finished change relies on,
marked verified (you read the code that shows it) or guessed (inferred,
and from what). Check every guess that is cheap to check, fix anything
found wrong, and show the author what is still guessed.
2. Browser test, once. Do not test between edits.
- If a change is large and depends on something you have not read, check that
one thing before building on it.
- A major update changes behavior, layout, scripts, styles, routing, the build,
or dependencies. A minor one changes only wording, documentation, comments,
patch notes, or data the project's own check script validates. Minor updates
ship without a browser test or an assumption check.
- Cheap checks that do not open a browser (a linter, a type check, a project
check script) may still run after minor edits.
- Batch the work: make every edit first, then test once at the end.
- When a test fails, fix it and rerun only the failing check, then run the full
test once before shipping.
- A test the author asks for always runs, whatever this rule says.
- Confirming that a deploy arrived, by comparing the deployed files with the
local copies, is not a test. It is cheap and still happens after every push.
- Where a session has standing permission to push, every change reaches
production, so decide by whether the change is major, not by whether it is
being pushed.
- Say what was not browser-tested in the summary. Never present an untested
change as tested.
Security
- Authentication model: how users are identified and sessions are managed
- Authorization model: what different user roles can and cannot do
- Data storage: what user data is stored, where, and how it is protected
- Environment variables: confirm no secrets are hardcoded; list all
variables that must be set in the environment and never committed
- Third-party trust: list every third-party service that receives user
data and what data it receives
- Known attack surface: any areas of the app with elevated risk and
what mitigations are in place
- Dependency policy: how dependencies are monitored for vulnerabilities
Repository Hygiene
Record the project's rule for what its version control carries and what it keeps out.
If the project already states one, document it and leave it alone. If it does not,
adopt the default below and write it in. This is a policy record rather than an
action: the audit reads the repository's configuration, writes the rule into the PRD,
and reports any gap as a discrepancy under Documentation Versus Reality. Creating or
editing an ignore file is a separate change, and nothing here authorises a version
control command that changes state, which steps 1 through 3 forbid and which stays
forbidden.
Commit message style and branching pattern are not covered here. They belong to
Conventions, which reads them from the history rather than from a rule, because two
sections governing one topic is how a document starts contradicting itself.
Default: the repository carries an ignore file and a `.gitattributes`, commits its
lockfile, keeps every secret out of history, and names its default branch `main`.
- Secrets are never committed, and this is the one item on the list whose cost is not
recoverable. An ignore rule keeps them out before they exist: ignore the whole
environment file family and re-include the example with a negation, `.env*` followed
by `!.env.example`, so the file listing key names travels with the repository and
the file holding values never does. The example carries every key name and no value,
which is the rule the Security section already states for the environment variable
reference.
Treat the ignore file as prevention, not protection. It stops a mistake that has not
happened yet and does nothing about one that has, so a project holding real secrets
pairs it with scanning and a secret manager rather than trusting it alone. Where the
audit finds a secret already committed, report it, name the file, and recommend
rotation. Do not rewrite history: it is destructive, it is outside this audit, and
it does not undo the exposure, because a pushed value is public from that moment.
- An ignore file exists wherever the project generates anything: build output,
dependency directories, caches, logs, coverage reports, and local editor or
operating system files. A project that generates nothing says so in the PRD rather
than carrying an empty file for the look of it.
- Lockfiles are committed, never ignored. A lockfile is what makes a build
reproducible, and ignoring one is the common inversion of this rule: the dependency
directory is what gets ignored, and the lockfile that pins it is what gets kept.
- Every ignore entry names something this project actually produces. A file copied
wholesale from a template lists rules for tools the project does not use, which is
worse than a short one because it buries what the project really generates. Where an
entry cannot be explained, say so rather than removing it unexamined.
- Ignoring a file does not untrack it. The rule applies only to files version control
is not already following, so anything committed before the rule was added stays
tracked and keeps being committed. This is the most common reason an ignore file
looks correct and does nothing, so compare the tracked list against the rules rather
than reading the rules alone.
- Generated output is sometimes committed on purpose, and the rule is to say why
rather than to forbid it. A site served directly from the repository, a vendored
build, or a file a tool regenerates that the deployment reads are all legitimate.
Record which files those are, what regenerates them, and what keeps them in step
with their source, because a generated file nobody knows is generated gets edited by
hand eventually.
- Pin line endings where the project is worked on across more than one platform, or
where any tool compares two copies of the same text byte for byte. `* text=auto
eol=lf` in `.gitattributes` makes a checkout produce the same bytes everywhere,
whatever each machine is configured to do. Fix it in the repository rather than in
each tool that reads the files, because the failure is silent rather than loud: a
comparison does not error, it reports a difference that is not there, and the
natural response is to correct the file that was already correct. Three things
belong in the same file. A format that must keep CRLF to run, such as a Windows
batch script, gets an explicit `eol=crlf` rule, because a blanket `eol=lf` breaks
it. Binary formats are marked as binary so they are never normalised or diffed as
text. Generated files can be marked as generated so they stay out of diffs and
language statistics.
- Large binaries are kept out of history. Every revision of one is stored forever, so
committing a handful repeatedly is what makes a clone slow years later, and the cost
cannot be removed afterwards without rewriting history. Where large files genuinely
have to be versioned, use the platform's large file mechanism and record that
decision, rather than committing them directly and discovering the cost later.
- Record in the PRD what the repository is and how to reach it: where the canonical
remote lives, the default branch name, and anything about the history a reader
should know. Someone cloning for the first time needs the first two, and neither can
be read from a file in the tree.
- Record the checks that decide whether the repository complies. These checks read and
report; they do not rewrite, and they never run a command that changes state.
- An ignore file exists, or the PRD says why the project needs none.
- No tracked file matches a pattern the ignore file claims to exclude. Report each
one, since this is the case where the rules look right and do nothing.
- No dependency directory, build output, or cache is tracked.
- No tracked file holds credentials by convention: an environment file other than
the example, a private key, a certificate, or a package manager configuration
carrying a token. Report by name and recommend rotation rather than acting.
- The lockfile is tracked, where the ecosystem has one.
- Where the project is worked on across platforms or compares file contents byte
for byte, `.gitattributes` exists and pins line endings, with an explicit rule
for any format that must keep CRLF.
- Every ignore entry corresponds to something the project produces, with any that
do not listed rather than removed.
Licensing
Record the project's licensing posture. If it already has a well defined licence,
document it and leave it alone: name the licence, point at the file, and state what
it permits and forbids. Only where the project has no licence, or has a bare licence
name with no licence text behind it, adopt this default and write both the policy
into the PRD and a `LICENSE.md` at the repository root, beside the README and never
inside /docs, for the detection reason given in the folder structure above. Markdown,
not plain text: the licence is a document people read, it belongs to the same doc set as
everything else this audit writes, and every platform that detects a licence file
recognises the `.md` extension.
Default posture: all rights reserved. Source-available, not open source. Publish a
`LICENSE.md` that grants nothing. The repository is published so it can be read, and
publishing is not a grant.
- Grant nothing by default. A permission given to everyone cannot easily be
withdrawn from one person. The goal is usually not to stop copying, it is to
retain the ability to act against a specific bad actor, and those two goals
conflict the moment the licence hands out broad permissions.
- The NO WAIVER clause is load-bearing. State that choosing not to act against a
use is not a licence, not a precedent, and not a waiver against that person or
anyone else; that delay does not waive; and that any waiver must be written,
signed, and scoped to the use it names. Without this, a long history of
tolerating copies is the first thing an infringer points at.
- Asymmetry rule: widening a grant is one sentence, narrowing a granted right is
not. When in doubt, grant less and offer the request route.
- Never assert a licence without the licence text. A bare "MIT" line in a README
with no `LICENSE.md` behind it is not a grant, it is an ambiguity. Either ship real licence
text or say nothing and let the default apply.
The one standing carve-out is AI and search referencing. Explicitly permit search
engines, AI assistants, answer engines, and other automated systems to crawl, index,
store for retrieval, quote, summarise, link to, and cite the work. Attribution is
requested, not required, and no permission needs to be asked for. Being cited in an
AI answer is the modern equivalent of ranking: it costs the project nothing and
gains it distribution, and enforcing against a citation works against the project's
own purpose. Draw the line at three distinct things:
- Referencing is granted.
- Substitution is not, meaning reproducing the work as a replacement for visiting
it.
- Training data is not granted by default, and is routed to the request path with a
note that it is not usually refused. Retrieval-and-cite is what actually produces
the citations, so this keeps the benefit without handing over a training licence.
Things the licence must not claim:
- Do not purport to override platform terms of service. A public repository on a
hosting platform already gives that platform's users whatever view and fork rights
its terms grant. State that those operate independently and are not enlarged by
the licence, rather than pretending to withhold them.
- Do not claim third-party data. Anything derived from an external API or a public
data source is not the project's to license. Say so explicitly.
- Do not restrict rights that cannot be restricted, such as fair use or fair
dealing.
Required sections of `LICENSE.md`: NO LICENCE IS GRANTED (covering express,
implied, and estoppel), AI, SEARCH, AND AUTOMATED ACCESS, NO WAIVER, PERMISSION, the
platform terms note, the third-party data note, NO WARRANTY, and any domain-specific
disclaimer the project needs.
Permission requests route to a public tracker rather than to private email, where
the project has one. If it is hosted on a platform with an issue tracker, name that
tracker's address for this repository. A visible record of what has and has not been
permitted suits a posture whose enforcement depends on permissions being specific and
traceable rather than assumed.
Keep the machine-readable layer consistent with the licence. Where the project
serves a site, `robots.txt` stays fully open (`User-agent: *` and `Allow: /`) and
carries a comment marking that as deliberate, so a future tightening is a decision
rather than an accident. Name `LICENSE.md` as authoritative if the two ever disagree.
A grants-nothing licence sitting next to an open `robots.txt` is a contradiction a
cautious crawler operator may resolve the wrong way.
Social Sharing Tags
Record the project's rule for the Open Graph and Twitter Card tags in each page's
head. If the project already states one, document it and leave it alone. If it does
not, adopt this default and write it in. This section is a policy record, not a
licence to edit pages: the audit reads the tags that exist, writes the rule into the
PRD, and reports any page that does not match it as a discrepancy under Documentation
Versus Reality. Editing a page head is a separate change, made deliberately and
outside this audit. As with robots.txt and sitemap.xml, this applies only where the
project actually serves a site.
The default is written for how one chat platform renders a pasted link, since that is
the strictest common case rather than a preference for that platform: the card is
narrow, mobile truncates aggressively, and the renderer falls back to the page title
tag or skips the embed entirely when og:title and og:description are absent. A page
that satisfies the strictest renderer satisfies the rest.
- Required on every shareable page: og:title, og:description, og:url, og:type,
og:site_name, and twitter:card. The first three are written per page. og:site_name
and og:type are the same across the site, and og:type is "website" unless a page is
genuinely an article.
- og:url is the absolute https URL of that specific page, never a relative path and
never the site root. This is the most common failure and it is a silent one: every
card still renders, and every one of them links back to the homepage no matter what
was shared. Take the canonical domain from what the project already has, its
sitemap.xml, a CNAME file, robots.txt, or the deploy config, and use it exactly,
including whether it carries a www prefix. Do not guess it.
- Character budgets, as safe caps rather than hard limits: og:title 60 characters
with 70 the absolute ceiling, og:description 150 with 200 the hard maximum, and
og:site_name 20. Renderers clip much later than this, near 256 and 350, but the
card is narrow and mobile shows far less, so those numbers are irrelevant in
practice. Emoji and markdown characters count as literal characters.
- og:title does not repeat the site name. The renderer already prints og:site_name as
small text directly above the title, so a title carrying it too produces visible
duplication and spends a third of the budget on something already on screen.
- Images are off by default. Do not add og:image, og:image:width, og:image:height, or
og:image:alt, and set twitter:card to "summary" rather than "summary_large_image",
because summary_large_image with no image renders an empty or broken frame in some
clients. A declared image that does not exist is worse than no image at all, so
og:image is never added speculatively or pointed at a placeholder. Where the project
already has an image sharing policy of its own, that rule wins, and the
requirements that go with it are: 1200 by 630 pixels at a 1.91:1 ratio, an absolute
https URL because a relative path fails silently, explicit og:image:width and
og:image:height so the card can be sized before the file finishes downloading, PNG
or JPG under about 8 MB, an og:image:alt under 100 characters, and only then
twitter:card set to "summary_large_image".
- The title front-loads the distinct part. The first three or four words carry the
page, because that is all a reader sees before deciding. No trailing branding, and
no colon stacking a subtitle onto a subtitle.
- The description is complete sentences stating what the page actually does, written
to end on a full stop rather than to be cut into one, since a sentence truncated
mid-word is what makes a card look broken. The tone is educational and pitched at
someone who has never been to the site and knows nothing about it: name the
concrete thing the page gives them, because a vague capability claim reads as
filler and gets scrolled past. It is not a restatement of the title. The two fields
are two chances to say something, not one thing said twice.
- Every description is based on the page's actual content, read from the page rather
than inferred from its filename, which is the same rule this audit applies
everywhere else. A description that overpromises is worse than a plain one, because
the reader finds out in one click. Where a page already carries a meta description
that is accurate, reuse it for og:description rather than inventing a second,
competing description, and where the two differ, say why the difference is
deliberate.
- Some pages are deliberately excluded: 404 and other error pages, mockups, scratch
or work in progress files, and anything already absent from sitemap.xml or marked
noindex. Sharing tags on those make a broken or unfinished address look legitimate
when it is pasted. List the exclusions in this section, so a later reader can tell
a decision from an oversight.
- Record the checks that decide whether a page complies, so compliance is something
run rather than argued about. Every page that should carry the tags has all six.
og:title is 70 characters or fewer, og:description 200 or fewer, og:site_name 20 or
fewer, with the actual count (counted by a script, not by eye) reported for anything over the target budgets so a
person can judge the borderline cases. Every og:url is absolute, begins with https,
and is unique across the site, since duplicate values are a bug rather than a style
choice. No og:title contains the og:site_name string. Where og:image is present,
the width, height, and alt tags are present too, its URL is absolute, and the file
it names exists in the repository. Where og:image is absent, twitter:card is
"summary". These checks read files and report; they do not rewrite them.
Page Titles
Record the project's rule for the title of each page. If the project already states
one, document it and leave it alone. If it does not, adopt this default and write it
in. As with Social Sharing Tags, this is a policy record rather than a licence to edit
pages: the audit reads the titles that exist, writes the rule into the PRD, and
reports any page that does not match it as a discrepancy under Documentation Versus
Reality. Changing a title is a separate change, made deliberately and outside this
audit. It applies only where the project actually serves a site.
The shape is "<unique page name> - <brand>", under two limits that measure different
things rather than compromising between two opinions. The first 30 characters must
identify the page on their own, without the brand and without the rest of the string.
The whole title is 60 characters or fewer. Truncation removes from the end, so a title
is read at two lengths at once: the first 30 characters are what survives on a tab
strip once three or four tabs are open, and the full 60 is what a search result
renders. Front-loading the distinct part satisfies both, so there is nothing to trade
off. The front budget is 30 rather than 50 because a tab is measured in pixels, not
characters, and a title of capitals and wide letters fills the same physical tab as a
longer one in lowercase.
- Front-load the distinct part and put the brand last. The brand is last precisely
because it is the part that can afford to be lost: a reader looking at the tab
already has the favicon in front of them. Brand-first collapses every tab on the
site to the same visible string, which defeats the one job a tab title has, and it
is the pattern a search engine is most likely to rewrite, because a title led by
boilerplate says nothing that distinguishes the page.
- The homepage inverts this, and only the homepage, because there the brand is the
distinct part, so it leads. Whether anything follows it is the project's call, and
the bare site name with no separator at all is a valid answer: it is correct
wherever the brand is already the thing people search for. Where it is not, a short
descriptor after the separator is what tells a stranger reading a search result what
the site actually is, and the homepage is usually the page where that matters most.
- Every page's first 30 characters are unique across the site. Two titles that differ
only after character 30 are the same title as far as a tab is concerned, so this is
stricter than requiring unique titles and it is the rule that matters.
- One separator, chosen once and used on every page. It costs 3 characters of the
budget, so count it. Where the project has no rule, use " - ", which matches the
single hyphen the Writing Style section already prefers in titles and headings.
- No placeholder titles. "Untitled", "Document", "Home", "index", and framework
defaults are failures. Search for them explicitly, since they survive from templates
and nobody notices them.
- The brand appears once, at the end. No keyword stuffing, and never repeat the brand
inside the page name.
- No emoji by default, since the favicon is already the visual marker in that tab, and
avoid all caps in the first 30 characters, which is the fastest way to spend the
pixel budget without spending the character budget.
- Write every title to survive being read months later with no site around it. A
bookmark saves the title as its name, and the bookmarks bar truncates harder than a
tab does. "Overview" is a usable tab title and a useless bookmark. This is the same
front-loading rule tested against the harsher case.
- Where the title changes at runtime, it must actually change on client-side
navigation. A single-page application that sets the title once in the head and never
again shows one title for every route, which is the most common failure in this area
and is invisible to anyone who checks a single page. State goes in front of the name
rather than behind it, because the front is what survives: "(3) Inbox - Acme". Error
and loading states get real titles too. A tab reading "Loading" for two seconds is
fine; one reading it forever, because the title is never replaced, is a bug.
- The title and og:title are different fields with different rules, and neither is
copied into the other. The title carries the brand as a suffix, because a tab and a
search result have nothing else to say who the site is. og:title omits it, because
the card already renders the site name directly above the title. Expect the two
strings to differ on the same page, and say so, rather than letting a later reader
treat the difference as a mistake.
- Record the checks that decide whether a page complies, so compliance is something
run rather than argued about. These checks read and report; they do not rewrite.
- A title exists on every page and is not a placeholder.
- Every title is 60 characters or fewer, with the actual count reported, counted by a script rather than by eye.
- The first 30 characters are unique across every page in the project. Report each
collision as a pair, since a collision is never one page's fault.
- The separator matches the one the project uses, on every page that has one.
- The brand suffix is present on every page except the homepage, and does not also
appear inside the page name.
- Where the site renders titles client-side, each route is loaded and the
resulting title is read, rather than the source being read. A title set once in
the head and never updated passes a source check and fails in a browser.
Deprecation and Removal
- Removal policy: first check whether the project already has a removal rule of its
own, stated in its docs, in a contributing guide, or established by a consistent
pattern in the changelog and the code. If it does, document that rule and leave it
alone. This audit records how the project works, it does not overrule how the
project has decided to work. Where an existing rule and the default below differ,
keep the existing rule and note the difference so the author can decide, rather
than silently replacing one with the other.
Only where the project states no rule, adopt this default and write it into the
PRD as the policy. Whether a removal needs a redirect is decided by whether the
thing being removed is public facing, not by the fact that it is being removed.
- Public facing: the deployed artifact and the addresses it serves. A live
URL or route, a published package, an exported name other code imports.
Removing one retires the address behind a redirect, alias, or equivalent
compatibility shim pointing at whatever replaces it, so the old address
keeps resolving.
- Internal: the source that builds the artifact, and anything else not
reachable from outside. Source files are not public facing even when their
names appear in a built URL, because the name is derived from the source
rather than being the contract. Removing one is a plain delete. No
redirect, no alias, no stub file, no tombstone. Nothing external is
pointing at it, so there is no address to preserve, and a permanent
compatibility entry would be maintenance in exchange for nothing.
Draw the line at the deploy boundary, and say in the PRD where the project puts
it, because a reader cannot apply the rule without knowing which side a given
file is on.
Adapt the mechanism to whatever the project actually has (a router redirect
map, a server rewrite rule, a deprecated re-export), and record the reasoning
alongside the rule so it is not relitigated later. If the project has no
redirect mechanism at all, say so, and state what it does instead.
- Public surface: list what is publicly addressable, item by item. This list is
whichever policy applies is applied against, so it has to be specific enough to
answer the question for any given file rather than gesturing at categories.
- Compatibility entries: where the project has them, state that they are
permanent, are never chained (a redirect always resolves to a real target in
one hop), and are never reused to point at different content later, since a
reused address silently serves the wrong thing, which is worse than a broken
link.
- Retired items: what has been removed, when, and what replaced it. A reader
who finds a reference to something that no longer exists should be able to
resolve it here.
- Historical records are not rewritten when something is removed. Changelog
entries and version history rows that describe a deleted item stay as they
are, because they record what happened at the time rather than describing the
current state.
Documentation Versus Reality
Record each discrepancy the checks in this audit found, and each one found by a
later update working through the verification checklist, rather than quietly
fixing it. Treat the code as the truth about what is, and the
documentation as the truth about what was intended.
- Documented features that do not exist in the code.
- Implemented features that appear in no documentation.
- Instructions, commands, paths, or file names in the docs that are wrong or stale.
- Version numbers, dependency lists, or structure diagrams that no longer match.
- Contradictions between two documents.
For each, state which source you would trust and why. Keep resolved entries in the
table with a note on how they were resolved, so the record shows what was found and
what was decided, not just the current state.
Risks and Open Questions
Be honest about the edges of the analysis. This section is worth more than the
confident parts of the document.
- Parts of the codebase you did not fully understand, and why.
- Fragile areas: files with no tests, complex logic, heavy coupling, obvious
workarounds, and anything marked TODO, FIXME, or HACK.
- Anything dangerous to change without more context, and what would break.
- Work already in progress: uncommitted changes, unmerged branches, half-finished
features, stubbed functions.
- Open questions for the author, numbered so they can be answered by reference.
When one is answered, fold the answer into the relevant section and record it
here as answered rather than deleting it.
Working Practice
The approach anyone, human or model, should take on future work in this project.
Written as concrete instructions, not principles.
- What to always check before editing, and which document to read first for which
kind of change.
- What never to do here, with the reason attached, so the rule survives contact
with someone who thinks they have a good exception.
- Where to look first for each kind of change, as a table mapping the kind of work
to the file to open.
- How to verify a change, including the exact command or manual check, and what to
update afterwards (patch notes, and the version line). Follow the Testing Cadence:
an assumption check and a browser test only right before a major update
ships (or is finished, where the project is not pushed anywhere).
- The docs/TODO.md rule from its specification above: before pushing (or when a
major update is finished, where nothing is pushed), check it and ask whether to
turn its ideas into researched Roadmap updates.
- The standing rules in CLAUDE.md, where the project has one: each rule, with a
line saying CLAUDE.md is the copy Claude reads and that the two change together.
- The verification checklist rule: when an update changes an area of the code,
check that area's PRD or DESIGN.md section against the code in the same
session, record any discrepancy, and mark the section verified with the date
on the Roadmap's verification checklist. Only the sections the update touches;
never the whole list at once.
Press Release
- Written as if the product has just launched publicly. Include
product name, what it does, who it is for, the key benefit, and a mock quote
from a fictional user. Written for a general audience, no jargon.
- Headline - one sentence naming the product and its core benefit, written as a live published announcement
- Subheadline - expands on the headline with one added detail or hook
- Dateline - city and release date
- Opening paragraph - covers who, what, when, where, and why in 3 to 5 sentences
- Problem statement - the specific pain point being solved, written from the customer perspective
- Solution description - how the product solves it, in plain non-technical language
- Customer quote - fictional but realistic quote from a named target persona
- Call to action - what the reader should do next (sign up, visit, download)
- Company boilerplate - one short paragraph describing the organization
Frequently Asked Questions
- External FAQ: 10-25 questions a real user would ask. Cover how it works,
what it costs, what data it uses, and what it does not do.
- Core definition and target audience
- Step by step usage summary
- Pricing and availability - cost, tiers, launch date, and regions
- Technical requirements - integrations, compatibility, and dependencies
- Competitive differentiation - how it differs from existing alternatives
- Known limitations - what the product does not do in v1
- Support and onboarding - how users get help and ramp up
- Internal stakeholder questions - ROI rationale, success metrics, and roadmap direction
---
After everything is updated, add these recent changes to PATCHNOTES.md and describe this process and how everything should be handled moving forward in PRD.md, including the date of this audit, so the next one can find what changed since.