# Prompt Guide — Generating ARCHITECTURE.md and AUDIT_CHECKLIST.md Use these prompts with any AI coding assistant (Claude, ChatGPT, Gemini, Cursor, Copilot, etc.) to generate or update your files. Copy the prompt, fill in the bracketed placeholders, and send it with your codebase attached or in context. Read `GUIDELINES.md` first — the prompts reference its rules. --- ## Section 1 — Generating ARCHITECTURE.md from scratch ### Prompt 1A — Full codebase audit (recommended first run) ``` Audit the entire codebase and produce a single markdown file called ARCHITECTURE.md. Follow this exact structure (required — a parser will read this file): --- # [Project Name] Architecture Audit > Generated: [TODAY'S DATE]. Read-only documentation — no fixes applied. ## 1. Pages & Screens — Data Fetched ## 2. Database Tables & Columns ## 3. Queries Run Per Page ## 4. Duplicate Data Fetching ## 5. Consistency Risks --- Rules for each section: **Section 1 — Pages & Screens:** - One H3 per page/screen. Format: ### `/route` — Page Title - Include: File path, Auth required (Yes/No), markdown table with columns: Data | Source | Function / Endpoint - Source must be the actual database or storage technology (SQLite, Turso, PostgreSQL, localStorage, etc.) **Section 2 — Database Tables & Columns:** - One H3 per table. Format: ### `table_name` (Database Name) - Markdown table with columns: Column | Type | Constraints | Notes - List indexes below each table **Section 3 — Queries Run Per Page:** - H3 heading matching the route from Section 1 - Each query in a fenced ```sql code block with a -- comment naming the function above it **Section 4 — Duplicate Data Fetching:** - List every case where the same data is fetched in more than one place - For each: H3 title, numbered list of fetch locations with file paths **Section 5 — Consistency Risks:** - Number each risk: ### 5.1, ### 5.2, etc. - For each: describe the risk, when it occurs, what the user sees - End each with: **Fix:** one-sentence recommendation - End each with: **Files:** comma-separated file paths Do not fix anything. Do not suggest refactors. Only document what the code does today. Write findings to the file as you go, one section at a time. ``` --- ### Prompt 1B — Large codebase (split into two passes) Use these two prompts in sequence when the codebase is too large for one pass. **Pass 1 — Schema and queries only:** ``` Read the entire codebase. Produce ARCHITECTURE.md with only Sections 1, 2, and 3: - Section 1: Every page/screen, its data sources, and its fetch functions - Section 2: Every database table with columns and indexes - Section 3: The exact SQL or ORM queries run per page, in fenced sql code blocks Format rules: - Section 1 H3s: ### `/route` — Page Title - Section 2 H3s: ### `table_name` (Database Name) - Section 3 H3s: match exactly the route used in Section 1 - Use backticks for all file paths, table names, column names, function names - Add: > Generated: [TODAY'S DATE]. Read-only documentation — no fixes applied. Do not write Sections 4 or 5 yet. Do not fix anything. ``` **Pass 2 — Issues only:** ``` Read ARCHITECTURE.md (already written) and the codebase. Add Section 4 (Duplicate Data Fetching) and Section 5 (Consistency Risks) to ARCHITECTURE.md. Section 4: List every case where the same query or data fetch happens in more than one place independently. Section 5: Number each risk 5.1, 5.2, etc. For each: describe the symptom, when it occurs, what the user sees. End with **Fix:** and **Files:** lines. Do not modify Sections 1–3. Do not fix anything. Append only. ``` --- ### Prompt 1C — Single page or feature audit ``` Audit only the [PAGE NAME / FEATURE NAME] feature and add it to ARCHITECTURE.md. For this feature, document: 1. All pages/screens involved (H3 heading per page, route format: `/route-path`) 2. All database tables it reads from or writes to 3. All queries it runs, in fenced sql blocks 4. Any data it fetches that is also fetched elsewhere in the app 5. Any consistency risks: data that could be stale, missing, or wrong Follow the same heading and table format as the existing entries in ARCHITECTURE.md. Do not modify existing entries. Append only. ``` --- --- ## Section 2 — Generating AUDIT_CHECKLIST.md from scratch ### Prompt 2A — Full checklist from ARCHITECTURE.md ``` Read ARCHITECTURE.md and produce AUDIT_CHECKLIST.md. Required structure: --- # [Project Name] — Audit Checklist > Source: `ARCHITECTURE.md` (generated [DATE]). No fixes applied yet. ## Critical — Data Inconsistency / Wrong Data Shown to User ## High — Slow Queries / Missing Indexes ## Low — Redundant Fetches / Minor Inefficiencies --- Rules for each item: - Format: - [ ] **Short title** (under 80 chars, include 5.N reference if from Section 5) - Next line (2 space indent): one or two sentence factual description of the symptom - Next line: _Fix:_ one-sentence action - Next line: _Files:_ `path/to/file`, `path/to/other` - No blank lines between description/Fix/Files of the same item - Blank line between separate items Severity assignment rules: - Critical: wrong data shown to user, data loss, security issue, auth bypass - High: page noticeably slow, redundant network calls, missing database index on a queried column - Low: minor redundancy, latent risk, cosmetic inefficiency Sort items within each group by user impact, most impactful first. Every item from Section 5 of ARCHITECTURE.md must appear in the checklist. ``` --- ### Prompt 2B — Prioritised checklist with fix order ``` Read ARCHITECTURE.md and produce AUDIT_CHECKLIST.md. Use the same format as Prompt 2A, then add a fourth section at the end: ## Recommended Fix Order List all items in the order they should be fixed, as a numbered list. For each: number, title, one-sentence reason why it comes before the next item. Prioritisation rules (in order): 1. Issues that affect every user on every visit 2. Issues that cause wrong data to be shown (not just missing data) 3. Issues in files that need to be touched anyway for other fixes (co-locate) 4. One-line fixes that unblock other fixes 5. Performance issues proportional to frequency × severity 6. Latent/defensive fixes last ``` --- --- ## Section 3 — Updating existing files ### Prompt 3A — Update ARCHITECTURE.md after code changes ``` The following changes were made to the codebase since ARCHITECTURE.md was last generated: [DESCRIBE CHANGES — e.g. "Added /api/reset route", "Renamed attempts table to user_attempts", "Added stats_reset_at column to session_config"] Update ARCHITECTURE.md to reflect these changes: 1. Update any affected entries in Sections 1–3 2. Remove any references to deleted routes, tables, or columns 3. Add any new routes, tables, or queries introduced 4. Review Section 4 — add or remove duplicates based on the new code 5. Review Section 5 — add new risks introduced, mark resolved ones as resolved with a note Update the > Generated: date at the top. Do not change anything unrelated to the described changes. ``` --- ### Prompt 3B — Update AUDIT_CHECKLIST.md after a fix is merged ``` The following fix was merged: [DESCRIBE FIX — e.g. "Added force-dynamic to /api/questions/list route"] Update AUDIT_CHECKLIST.md: 1. Mark the relevant item(s) as - [x] (done) 2. Add a short note inline if the fix was partial: _Partial fix: [what remains]_ 3. If the fix introduced a new issue, add a new item in the appropriate severity group 4. Do not delete any items — only mark them done Do not change any other items. ``` --- ### Prompt 3C — Add a new feature to both files ``` A new feature was added: [FEATURE NAME AND DESCRIPTION] Update both ARCHITECTURE.md and AUDIT_CHECKLIST.md: For ARCHITECTURE.md: - Add the new page(s) to Section 1 with route, file path, auth, and data table - Add any new database tables to Section 2 - Add the queries to Section 3 - Check Section 4 — does this feature duplicate any existing fetches? - Check Section 5 — does this feature introduce any consistency risks? For AUDIT_CHECKLIST.md: - Add any new issues introduced by this feature in the appropriate severity group - If this feature resolves any existing issues, mark them [x] Follow all format rules from GUIDELINES.md exactly. ``` --- --- ## Section 4 — Converting an existing audit to this format ### Prompt 4A — Convert a Notion / Google Doc audit ``` I have an existing audit document pasted below. Convert it into two files: 1. ARCHITECTURE.md — following the structure in GUIDELINES.md Section 1 2. AUDIT_CHECKLIST.md — following the structure in GUIDELINES.md Section 2 Where information is missing (e.g. exact file paths, SQL queries), add a placeholder: [NEEDS VERIFICATION] so I can fill it in manually. Do not invent information. If a section cannot be populated from the source document, write: > Section incomplete — requires codebase review. --- EXISTING AUDIT --- [PASTE YOUR DOCUMENT HERE] ``` --- ### Prompt 4B — Convert GitHub Issues to AUDIT_CHECKLIST.md ``` I have the following GitHub issues from my repository. Convert them into AUDIT_CHECKLIST.md format. Rules: - Map issue labels to severity: `bug` or `data-integrity` → Critical, `performance` → High, `chore` or `tech-debt` → Low. If no label, use your judgment based on the issue description. - Use the issue title as the checklist item title (shorten if over 80 chars) - Use the issue body as the description (one or two sentences max — summarise if longer) - For _Fix:_ use the first comment marked as a solution, or derive from the issue body - For _Files:_ use any file paths mentioned in the issue, or write [UNKNOWN] - Closed issues → - [x]. Open issues → - [ ] --- ISSUES --- [PASTE GITHUB ISSUES HERE] ``` --- ## Tips for best results - **Give the AI the actual code files**, not just descriptions. Accuracy drops significantly when it works from memory. - **Run Pass 1 and Pass 2 separately** for codebases over ~3,000 lines. One giant pass risks shallow coverage. - **Always review before using.** AI-generated audits miss things. Read every entry before dropping the file into the diagram tool. - **Keep ARCHITECTURE.md read-only.** Never mix fixes into it. If you update the code, update the doc — don't use the doc to track fixes (that's what the checklist is for). - **Version both files in git.** The diff over time is as valuable as the current snapshot.