Improve doc audit AI prompt (#558)

Author: AlexJSully

.github/prompts/audit-docs.md

@@ -10,56 +10,83 @@ labels:
     - 'mermaid'
 ---
 
-Purpose:
-While reviewing the #activePullRequest, analyze the entire #codebase and ensure
-that the #file:docs directory is fully up to date, consistent, and accurate based
-on the current implementation.
-
-What to do:
-
-1. Audit the `docs/` directory against the real codebase
-    - Identify documentation gaps, inaccuracies, outdated explanations, or missing sections.
-    - Cross-check code comments, architecture, directory structure, core modules, exposed APIs, utilities, and workflows.
-
-2. Update documentation as necessary
-    - Revise outdated sections.
-    - Add missing content.
-    - Rewrite unclear explanations.
-    - Add short code snippets where they meaningfully clarify how something works.
-
-3. Use visual diagrams as frequently as appropriate
-    - Prefer Mermaid diagrams to explain architecture, flows, relationships, state transitions, data movement, or component interactions.
-    - Choose diagram types that best communicate the system (e.g., `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram`, `gitGraph`).
-    - When explaining logic, system or architecture, include Mermaid diagrams when applicable.
-
-4. Ensure architectural accuracy
-    - Validate that the documented behavior matches real code.
-    - If implementation diverges from existing docs, update docs to match real behavior.
-
-5. Maintain a concise, structured writing style
-    - Keep explanations clear and self–contained.
-    - Avoid unnecessary verbosity.
-    - Highlight important behaviors or assumptions explicitly.
-
-6. Make changes directly
-    - Modify documentation files.
-    - Add new files if needed.
-    - Update diagrams.
-    - Include only meaningful and defensible changes; do not generate placeholder text.
-
-Goal:
-Produce a clean, accurate, comprehensively updated `docs/` directory that fully
-reflects the current implementation, backed by diagrams and practical examples.
-
-Acceptance checklist (use as review checklist):
-
-- [ ] Audit `docs/` for correctness against actual code
-- [ ] Fix or update inaccurate/outdated pages
-- [ ] Add missing sections or examples
-- [ ] Add Mermaid diagrams where helpful
-- [ ] Ensure examples are runnable/accurate
-- [ ] Run repository `validate` (format, lint and testing) are passing and fix markdown lint issues. For example #file:package.json `npm run validate`
-
-Notes:
-
-- Prefer concrete changes only; avoid adding placeholders or speculative content.
+**Purpose:**
+While reviewing this #activePullRequest, analyze the entire #codebase and ensure the #file:docs directory is accurate, up to date, and fully aligned with the current implementation.
+
+---
+
+## HARD RULES (Do Not Violate)
+
+1. **No forward-looking or speculative content.**
+    - Do NOT generate a `roadmap.md`.
+    - Do NOT document planned features, hypothetical designs, or imagined improvements.
+    - Document only what exists in the current codebase.
+
+2. **No invented code.**
+    - Only reference functions, hooks, classes, types, modules, files, directories, system architecture & design or packages that actually exist.
+    - Verify existence before describing or linking anything.
+
+3. **No placeholder text or TODOs.**
+    - Do not create empty sections or stubs.
+    - Every sentence must be grounded in verifiable code.
+
+4. **No unnecessary rewriting of the entire system.**
+    - Only update documentation that is outdated, incorrect, incomplete, or missing.
+
+---
+
+## What to Do
+
+### 1. Audit the `docs/` directory
+
+- Identify inaccuracies, outdated content, missing explanations, or architectural mismatches.
+- Cross-reference source files, comments, directory structure, and actual behavior.
+
+### 2. Update documentation strictly based on verified code
+
+- Correct outdated statements.
+- Add missing explanations grounded in the current implementation.
+- Include **small, accurate code snippets** whenever explaining behavior, usage, or examples.
+    - Snippets must reference real code that exists within the codebase.
+    - No invented identifiers.
+
+### 3. Use **Mermaid diagrams extensively**
+
+- Proactively identify any section where a diagram would improve clarity.
+- Include diagrams for:
+    - data flows
+    - module interactions
+    - component relationships
+    - lifecycle steps
+    - architectural overviews
+    - system interactions
+- Use only diagrams that reflect **actual, current code** (no hypothetical structures).
+- Prefer `flowchart`, `sequenceDiagram`, `classDiagram`, and `stateDiagram` when appropriate.
+
+### 4. Reference real files frequently using markdown links
+
+- Whenever referencing a file or module, **link directly to the file using proper markdown**: `[Description](relative/path/to/file.ts)`
+- Confirm the file exists before linking.
+- Use file links liberally so readers can immediately navigate to source.
+
+### 5. Maintain clarity and conciseness
+
+- Keep explanations self-contained and clear.
+- Highlight real architectural decisions, assumptions, and edge cases.
+- Avoid verbosity or speculative commentary.
+
+### 6. Apply changes directly (docs only)
+
+- Modify existing documentation files.
+- Add new markdown files only when supported by real code.
+- If creating a **new directory**:
+    - **a. Always create an `index.md`**
+        - Must provide an overview of the directory’s purpose and contents.
+    - **b. Create only files that correspond directly to real, existing code.**
+- No speculative or forward-looking directories or files.
+
+---
+
+## Final Step
+
+After completing all changes, run `npm run validate` from #file:package.json and ensure markdown linting passes cleanly.

docs/architecture/components/projects.md

@@ -32,14 +32,21 @@ flowchart LR
 ```
 
 ```ts
-{
-  name: 'Project Name',
-  title: 'Project Title',
-  employer: 'Employer',
-  thumbnail: 'image/path',
-  links: [{ type: 'github', url: '...' }],
-  // ...other fields
-}
+// Example project object (see src/data/projects.ts)
+const example = {
+	id: 'my-project',
+	name: 'My Project',
+	title: 'Lead Developer',
+	employer: 'Example Co',
+	employerURL: 'https://example.com',
+	url: 'https://example.com/my-project',
+	urls: [{ text: 'GitHub', tooltip: 'Source', icon: /* Svg icon */ () => null, url: 'https://github.com/example' }],
+	color: '#047a6b',
+	dates: { startDate: '2023-01', endDate: '2023-12' },
+	showcase: true,
+	objectFit: 'contain',
+	youtubeURL: 'https://www.youtube.com/embed/VIDEO_ID?mute=1',
+};
 ```
 
 ## 🔗 Related Docs

docs/architecture/data.md

@@ -79,7 +79,7 @@ sequenceDiagram
 
 ## 🔗 Related Docs
 
-- [Component Documentation](../components/index.md)
+- [Component Documentation](./components/index.md)
 - [System Architecture](./index.md)
 
 💡 **Tip:** Use TypeScript interfaces for all data structures to ensure type safety and maintainability.

docs/architecture/helpers.md

@@ -21,17 +21,25 @@ Helpers provide reusable utility functions for formatting, logic, and data manip
 ### ASCII Art Helper
 
 ```ts
-import { asciiArt } from '@helpers/ascii';
+import { consoleLogLogo, debounceConsoleLogLogo } from '@helpers/ascii';
 
-console.log(asciiArt('Portfolio'));
+// Print ASCII logo once
+consoleLogLogo();
+
+// Debounced version for repeated calls
+debounceConsoleLogLogo();
 ```
 
 ### Custom Logic Helper
 
 ```ts
-import { aaaahhhh } from '@helpers/aaaahhhh';
+import { aaaahhhh, convertAAAAHH } from '@helpers/aaaahhhh';
+
+// Run the playful page-wide transform
+aaaahhhh();
 
-const result = aaaahhhh('Hello!');
+// Convert text to the AAAAHHHH form
+const converted = convertAAAAHH('Hello World');
 ```
 
 ## 🧩 Integration & Relationships

docs/architecture/images.md

@@ -91,7 +91,7 @@ import GitHubIcon from '@images/icons/github.svg';
 
 ## 🔗 Related Docs
 
-- [Component Documentation](./components.md)
+- [Component Documentation](./components/index.md)
 - [Projects Guide](./components/projects.md)
 
 ---

docs/architecture/index.md

@@ -46,7 +46,7 @@ flowchart TD
 
 ## 🧩 Subsystems
 
-- **Components:** UI elements (see [Components Docs](../components/index.md))
+- **Components:** UI elements (see [Components Docs](./components/index.md))
 - **Data:** Static and dynamic data sources
 - **Helpers/Utils:** Utility functions for logic and formatting
 - **Layouts:** Page and section layouts
@@ -56,7 +56,7 @@ flowchart TD
 ## 🔗 Related Docs
 
 - [Usage Guides](../usage/index.md)
-- [Component Documentation](../components/index.md)
+- [Component Documentation](./components/index.md)
 
 ---
 

docs/architecture/layouts.md

@@ -30,7 +30,7 @@ export default function Page() {
 ## 🔗 Related Docs
 
 - [System Architecture](./index.md)
-- [Component Architecture](./components.md)
+- [Component Architecture](./components/index.md)
 
 ---
 

docs/usage/index.md

@@ -2,18 +2,18 @@
 
 This section provides practical guides for installing, configuring, running, and using the AlexJSully Portfolio project. It is designed for both newcomers and experienced developers.
 
-## 📦 Topics Covered
+## Topics Covered
 
 - [Setup & Installation](./setup.md)
-- [Feature Guides](../components/index.md)
-- [Testing](../testing.md)
+- [Feature Guides](../architecture/components/index.md)
+- [Testing](./testing.md)
 
-## 🏁 Quick Start
+## Quick Start
 
 See [Setup & Installation](./setup.md) for step-by-step instructions.
 
-## 🔗 Related Docs
+## Related Docs
 
 - [Architecture Overview](../architecture/index.md)
-- [Component Documentation](../components/index.md)
-- [Testing](../testing.md)
+- [Component Documentation](../architecture/components/index.md)
+- [Testing](./testing.md)