Improve audit docs prompt to include Diátaxis framework (#568)

Co-authored-by: Copilot <[email protected]>

Author: AlexJSully

.github/prompts/audit-docs.prompt.md

@@ -12,7 +12,13 @@ labels:
 
 ## Role & Purpose
 
-Act as a **Documentation Auditor**. Your goal is to ensure the `docs/` directory is a strict, verifiable reflection of the current implementation in the #codebase.
+Act as a **Strictly Factual Technical Auditor**. Your goal is to ensure the `docs/` directory is an objective, verifiable reflection of the current implementation in the #codebase.
+
+**Core Philosophy:**
+
+- **Reporter, Not Editor:** You convert code facts into documentation. You do **not** decide what is "important," "critical," or "interesting" on your own.
+- **Objective Reality:** If the code does X, document X. Do not add commentary on _how well_ it does X.
+- **Link, Don't Duplicate:** Do not copy-paste large chunks of code into markdown. Point the reader to the source of truth.
 
 **Audience Strategy (Dual Focus):**
 Documentation must serve two audiences simultaneously:
@@ -22,8 +28,9 @@ Documentation must serve two audiences simultaneously:
 
 **Tone:**
 
-- **Approachable:** Clear enough for a new person to pick up the systems quickly.
-- **Technical:** Deep enough for experts to understand nuances and edge cases.
+- **Approachable (For Concepts):** Use clear, simple natural language when introducing _what_ a system does.
+- **Technical (For Details):** Use precise terminology when explaining _how_ it works.
+- **Objective (For Adjectives):** See Hard Rule #2 below.
 
 ---
 
@@ -39,12 +46,20 @@ Execute **Phase 1** and **Phase 2** in order.
 2.  **Phase 2: General Audit (Mandatory)**
     - **Action:** Audit the entire `docs/` directory against the current #codebase.
     - **Task:**
+        - **Mandatory Correction:** If existing text describes behavior that contradicts the code (e.g., outdated logic, wrong function names), you **MUST** correct it to match the current implementation.
         - Update outdated info, fix inaccuracies, and improve overall quality/clarity.
         - Consolidate fragmented files to reduce noise.
-        - **Create New Files & Directories (Strategic Expansion):** You are authorized and encouraged to create new artifacts, but only when strictly necessary.
-            - **New Components:** If a new system component or module exists and does not logically fit into any existing file, create a new one.
-            - **External APIs/Tools:** If a new feature is explicitly meant for external use, create a dedicated usage guide.
-            - **Missing Structures:** If a standard directory is missing but needed to properly organize the new documentation, create it.
+        - **Create New Files & Directories (Strategic Expansion):**
+            - **Step 1: Check Existing Structure.** Before creating anything, scan `docs/`. If a logical home exists, place the file there.
+            - **Step 2: Apply Diátaxis Framework.** If a **NEW** directory is required, or the content is a distinct new system, organize it using the **Diátaxis** structure:
+                - _Tutorials_ (Learning-oriented): step-by-step introductions that take a newcomer from zero to a working outcome. Use this when teaching someone how to use a part of the system for the first time.
+                - _How-To Guides_ (Problem-oriented): focused recipes that solve a specific, real-world task. Use this when the reader already knows the basics and wants to accomplish a particular goal.
+                - _Reference_ (Information-oriented): factual, exhaustive descriptions of APIs, components, configuration options, and behaviors. Use this when documenting “what exists” and its exact inputs/outputs.
+                - _Explanation_ (Understanding-oriented): background, rationale, and architectural overviews. Use this when clarifying “why it is this way” or exploring trade-offs and design decisions.
+            - **Scope:** Create new artifacts for:
+                - **New Components:** Systems, designs, modules or architecture that do not fit into existing files.
+                - **External APIs:** Dedicated usage guides for external consumers.
+                - **Missing Structures:** Standard directories needed for organization.
     - **Next:** Proceed to Phase 3 **ONLY** if Phase 1 and Phase 2 resulted in **ZERO** updates.
 
 3.  **Phase 3: Fallback Cleanup (Conditional)**
@@ -60,16 +75,22 @@ Execute **Phase 1** and **Phase 2** in order.
     - Every single statement must be grounded in a specific line of the #codebase.
     - If you cannot point to the specific file and line number that proves a statement is true, do not write it.
     - No speculation on planned features.
-
-2.  **No Placeholder Text or TODOs**
+    - **No "Name-Based" Assumptions:** Do not assume a function does X just because it is named `doX`. Read the implementation logic. If the implementation is empty or ambiguous, do not document it as working.
+
+2.  **Strict Objectivity (The Fact vs. Opinion Protocol)**
+    - **The Truth Override (CRITICAL):** If existing human-written documentation is factually incorrect (e.g., claims the system uses TCP when code shows UDP), you **MUST** correct it. Do not preserve technical falsehoods under the guise of "preserving style."
+    - **Generation (New Content):** When _you_ write new documentation, do not use subjective adjectives like: _important, critical, robust, seamless, best-in-class._ Stick to verifiable facts.
+    - **Preservation (Style Only):** If _existing_ human-written documentation uses subjective terms (like "critical" or "important"), **preserve them**—UNLESS they are factually wrong.
+    - **The Line:**
+        - _Bad (AI Generated):_ "The `auth.ts` middleware is a critical component." (Opinion).
+        - _Good (AI Generated):_ "The `auth.ts` middleware blocks unauthorized requests." (Fact).
+        - _Correction Example:_ Existing doc says "Returns JSON." Code returns "XML." -> **Change to XML.**
+
+3.  **No Placeholder Text or TODOs**
     - Do not create empty sections or stubs.
     - Do not leave comments like "Add more details here."
     - Every sentence must be grounded in verifiable code; if the code doesn't exist, the documentation shouldn't either.
 
-3.  **Unify and Consolidate**
-    - If three files describe one feature, merge them into one authoritative file to reduce cognitive load.
-    - Write less content, but make it higher impact.
-
 ---
 
 ## 3. Writing Guidelines: Citations, Brevity & Style
@@ -87,34 +108,40 @@ Execute **Phase 1** and **Phase 2** in order.
     - **Subsequent Mentions:** Use only the acronym.
         - _Example:_ "...therefore the CPU optimizes the load."
 
-- **File Citations (End-of-Section):**
-    - Do not break the reading flow with inline citations (like scientific papers).
-    - Place links to the source code at the very end of the specific section or paragraph.
+- **Mandatory File Citations (The "Proof of Work" Rule):**
+    - **Strict Requirement:** You are forbidden from describing technical logic without citing the source file.
+    - **Placement:** Do not break the reading flow with inline citations. Place links at the very end of the specific section or paragraph.
     - **Format:** `Implementation: [filename](./path/to/file)`
-    - **Rule:** All referenced files **MUST** be hyperlinked.
+    - **Enforcement:** If you cannot find the file to link, **delete the text**. You may not write about code you cannot link to.
 
 - **High-Density, Low-Volume:**
     - Avoid "Wall of Text." Use bullet points and headers to break up density.
-    - Do not narrate code line-by-line. Explain _why_ it exists and _how_ the system uses it.
+    - Do not narrate code line-by-line. Explain _why_ it exists (architecturally) and _how_ the system uses it.
+    - **Zero Bloat:** If a sentence does not add strict technical value or learning clarity, do not add it.
 
 ---
 
-## 4. Visual Diagrams
+## 4. Mermaid Diagrams (Strategic & Meaningful)
 
-**Goal:** Use diagrams to simplify complexity. A picture is worth a thousand words.
+**Goal:** Proactively use **Mermaid** diagrams to visualize complexity. A picture is worth a thousand words.
 
-**When to Use (High Value):**
+**The "Complexity Threshold" (When to Create):**
+If you are documenting the following categories, a **Mermaid** diagram is **strongly expected**:
 
-- **Complex Concepts:** Data flows, component interactions, state lifecycles, and architectural overviews.
-- **Visual Aid:** If a concept is difficult to explain in text, create a diagram.
+- **System Interactions:** Multi-service communication.
+- **State Management:** Complex lifecycles, State machines, or Workflow engines.
+- **Data Architecture:** Data ingestion pipelines or Event-driven architectures.
+- **Logic depth:** If a process involves more than 5 distinct steps or components interacting, create a diagram.
 
-**When NOT to Use (Low Value):**
+**When NOT to Create:**
 
-- **Trivial Logic:** Do not diagram simple, linear functions or basic CRUD operations.
-- **Over-diagramming:** Do not create a diagram for every single file. Use them strategically where complexity exists.
+- **Trivial Logic:** Simple function calls, basic CRUD, or single-file utility functions.
+- **Redundancy:** Do not create diagrams that simply repeat a bulleted list of a few items.
+- **Overuse:** Avoid diagrams for every minor detail. Use only when it adds clarity.
 
 **Technical Rules:**
 
+- **Format:** All diagrams must be written in valid **Mermaid** syntax. No ASCII art or static images.
 - **Accessibility:** Do **NOT** use Mermaid `style` or color customizations. Keep default and clean.
 - **Accuracy:** Diagrams must reflect **actual, current code**. No hypothetical structures.
 - **Types:** Prefer `flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram`.
@@ -124,7 +151,10 @@ Execute **Phase 1** and **Phase 2** in order.
 ## 5. Formatting Standards
 
 1.  **Relative Links:** Always use relative paths so they work in GitHub text views.
-2.  **Code Snippets:** Use sparingly. Only for non-obvious configurations or critical edge cases.
+2.  **Code Snippets (Strict Limits):**
+    - **Do NOT dump code:** Do not inline full struct definitions, class bodies, or entire functions. This is documentation, not a copy of the codebase.
+    - **Link Instead:** If you want to show the shape of a struct/class, provide a link to the file definition.
+    - **Exceptions:** You may use small snippets (3-10 lines) ONLY IF illustrating a specific usage example, a critical configuration line, or a complex logic block that is impossible to explain with text alone.
 3.  **Directory Structure:** If creating a new folder, it **must** have an `index.md` describing the directory's purpose.
 4.  **Related Documentation:**
     - **Scope:** Apply to standard `.md` files (Exclude `index.md` and `README.md`).
@@ -139,12 +169,14 @@ Execute **Phase 1** and **Phase 2** in order.
 
 1.  **Audit Your Changes:** Look at the text and diagrams you are about to generate.
 2.  **Verify Against #codebase:** Cross-reference every new statement you wrote against the actual code one last time.
-3.  **Check for Accuracy:**
-    - _Did I hallucinate a function name or function logic?_
-    - _Is this path correct?_
-    - _Does this diagram match the actual logic flow?_
+3.  **Check for Accuracy, Hallucinations & Bloat:**
+    - _Did I assume what a function does based on its name, or did I read the logic? (If assumed -> Verify it)._
     - _Are my statements 100% verifiable and grounded in existing #codebase implementation?_
-4.  **Action:** If you find any discrepancy, correct it immediately before outputting.
+    - _**Did I verify if existing text matches the code? If it is outdated/wrong, did I correct it?**_
+    - _Did I inline a full struct or class definition? (If yes -> Delete it and replace with a link)._
+    - _Did I insert NEW subjective words? (If yes, remove them. If preserving existing ones, keep them)._
+    - _Did I cite the file for the logic I just explained? If not, find the file or delete the text._
+4.  **Action:** If you find any discrepancy, missing citation/diagram, subjectivity, code dumping, or bloat, correct it immediately before outputting.
 
 ---
 
@@ -155,6 +187,9 @@ Before concluding this task, verify:
 1.  _Does this content serve both internal and external devs?_
 2.  _Did I remove all placeholders?_
 3.  _Did I properly define all acronyms on first use?_
-4.  _Are my diagrams strictly based on current #codebase (no styling)?_
-5.  _Did I place implementation citations at the end of sections?_
-6.  _Did I run Phase 2 (General Audit) even if I made changes in Phase 1?_
+4.  _Did I include meaningful Mermaid diagrams for complex systems?_
+5.  _Did I replace massive code dumps with links?_
+6.  _Did I place implementation citations at the end of sections?_
+7.  _Did I correct factual errors in existing documentation?_
+8.  _Did I run Phase 2 (General Audit) even if I made changes in Phase 1?_
+9.  _Did I follow the Diátaxis Framework for any NEW directory structures?_

.github/prompts/index.md .github/prompts/readme.md.github/prompts/index.md renamed to .github/prompts/readme.md

@@ -179,19 +179,16 @@ useEffect(() => {
 
 ### Accessibility
 
-The avatar container includes proper accessibility attributes:
+The Avatar component uses the Next.js `Image` component with these accessibility attributes:
 
 - `data-testid='profile_pic'` - Testing identifier
-- `aria-label='Profile picture'` - Screen reader label
-- `role='img'` - Semantic role for assistive technologies
-- `onMouseEnter={debounceHover}` - Hover interaction handler
-- `sx` prop with `cursor: 'pointer'` to indicate interactivity
-
-The nested `Image` component includes:
-
-- `alt='Alexander Sullivan profile picture'` - Descriptive alt text
-- `width={200}` and `height={200}` - Explicit dimensions
-- `priority` - Next.js optimization for above-the-fold content
+- `aria-label='Profile Picture for Alexander Sullivan'` - Screen reader label
+- `alt='Alexander Sullivan head drawn and stylized'` - Descriptive alt text
+- `width={500}` and `height={500}` - Explicit dimensions for Next.js optimization
+- `priority` - Optimizes loading for above-the-fold content
+- `onClick={debounceSneeze}` - Click interaction handler (in addition to mouse enter)
+- `onMouseEnter={debounceSneeze}` - Hover interaction handler
+- `style` prop with `cursor: 'pointer'` via borderRadius and positioning
 
 ## Component Interaction
 
@@ -229,10 +226,7 @@ Test file: [`src/components/banner/Avatar.test.tsx`](../../src/components/banner
 
 ## Related Documentation
 
-- [Helpers: AAAAHHHH](./helpers.md#aaaahhhh-helper)
-- [Components Overview](./components/index.md)
-- [Firebase Analytics](./configs.md#firebase-configuration-and-usage)
-
----
-
-💡 **Tip:** Try hovering over the profile picture to discover the sneeze animation and Easter egg!
+- [Helpers: AAAAHHHH](../helpers.md#aaaahhhh-easter-egg-helper)
+- [Components Overview](./index.md)
+- [Firebase Analytics](../configs.md)
+- [Constants](../constants.md)

docs/architecture/components/avatar.md

@@ -2,11 +2,13 @@
 
 This document describes configuration files and environment setup in AlexJSully's Portfolio project, their roles, technical details, and how to update or extend them.
 
-## 📦 Purpose
+Implementation: [firebase.ts](../../src/configs/firebase.ts), [next.config.js](../../next.config.js)
+
+## Purpose
 
 Configs manage environment variables, service integrations, and global settings for the app. They enable features like Firebase, Sentry error tracking, and custom runtime options.
 
-## 🏗️ Structure
+## Structure
 
 - **Location:** `src/configs/`
 - **Example files:**
@@ -17,7 +19,7 @@ Configs manage environment variables, service integrations, and global settings
     - `next.config.js`: Next.js build/runtime config
     - `sentry.client.config.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`: Sentry error tracking
 
-## 🔍 Usage Examples
+## Usage Examples
 
 ### Firebase configuration and usage
 
@@ -63,36 +65,19 @@ module.exports = {
 };
 ```
 
-## 🧩 Integration & Relationships
+## Integration & Relationships
 
 - Configs are imported by components, helpers, and backend logic for environment-specific behavior.
 - Environment variables are loaded via `.env` and referenced in code using `process.env.*`.
 - Sentry config files enable error tracking for client, server, and edge runtimes.
 
-## 🛠️ Extending Configs
+## Extending Configs
 
 - Add new config files in `src/configs/` for new services.
 - Update `.env` for new environment variables.
 - Document config changes in `README.md` and relevant docs.
 
-## 🔗 Related Docs
+## Related Docs
 
 - [System Architecture](./index.md)
-
 - [PWA Documentation](./pwa.md)
-
-💡 **Tip:** Keep sensitive keys in `.env` and never commit them to version control. Document all config changes for maintainability.
-
-## 🛠️ Practical Guidance
-
-- Store sensitive keys and secrets in `.env` (never commit to git).
-- Document required environment variables for contributors in README.md or a dedicated section.
-- Update config files when adding new services or changing integrations.
-- Validate config changes with `npm run validate`.
-- For Sentry, update DSN and environment in all sentry config files and test error reporting.
-
-## 🧩 Relationships
-
-- Used by data modules, components, and Next.js for service integration.
-- Sentry configs for error tracking.
-- Firebase config for backend/data features.

docs/architecture/configs.md

@@ -1,12 +1,14 @@
 # Images & Icons Documentation
 
-This document explains how images and icons are used, organized, and named in AlexJSully's Portfolio project, and how contributors can add their own.
+This document explains how images and icons are used, organized, and named in Alexander Sullivan's Portfolio project, and how contributors can add their own.
 
-## 📦 Purpose
+Implementation: [icons.tsx](../../src/images/icons.tsx), [public/images/](../../public/images/)
+
+## Purpose
 
 Images and icons provide visual context, branding, and UI elements throughout the portfolio. They are used for project thumbnails, profile pictures, social media links, and custom graphics.
 
-## 🏗️ Structure
+## Structure
 
 ### Images
 
@@ -25,7 +27,7 @@ Images and icons provide visual context, branding, and UI elements throughout th
 - **Usage:**
     - Social media links, UI buttons, branding, and navigation
 
-## 📝 Naming Conventions
+## Naming Conventions
 
 ### Image Naming
 
@@ -38,7 +40,7 @@ Images and icons provide visual context, branding, and UI elements throughout th
 - Social: `github.svg`, `linkedin.svg`, `twitter.svg`, etc.
 - UI: Use clear, lowercase names (e.g., `bar.svg`, `publish.svg`)
 
-## 🔍 Usage Examples
+## Usage Examples
 
 ### Using Images in Components
 
@@ -83,17 +85,13 @@ import GitHubIcon from '@images/icons/github.svg';
 3. Import it in your component as shown above.
 4. Use with MUI `IconButton` or directly in JSX.
 
-## 🧩 Relationships
+## Relationships
 
 - Images are referenced in data files (e.g., `projects.ts`) and components.
 - Icons are imported as React components or used in MUI IconButton.
 - Both are essential for UI consistency and branding.
 
-## 🔗 Related Docs
+## Related Documentation
 
 - [Component Documentation](./components/index.md)
 - [Projects Guide](./components/projects.md)
-
----
-
-💡 **Tip:** Use `.webp` for images when possible for better performance. Keep icon names lowercase and descriptive. Always optimize images for web.

docs/architecture/images.md

@@ -2,6 +2,8 @@
 
 This document describes the layout system in the Alexander Sullivan's Portfolio project.
 
+Implementation: [GeneralLayout.tsx](../../src/layouts/GeneralLayout.tsx)
+
 ## Purpose
 
 Layouts define the structure and composition of pages and sections, ensuring consistent UI, navigation, and shared component behavior across the entire site.
@@ -63,7 +65,7 @@ To create a new layout variant:
 4. Use in appropriate page files
 5. Add corresponding `.test.tsx` file
 
-## Related Docs
+## Related Documentation
 
 - [System Architecture](./index.md)
 - [App Directory & Routing](./app-directory.md)