Improve all prompt docs (#578)

Improve all agentic prompt docs to work better with VSCode's GitHub
Copilot by making them shorter and more focused.

In addition, ran those prompts and their code changes are included in
this PR.

Author: AlexJSully

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

@@ -58,79 +58,42 @@ targets:
 
 ### [`audit-pr.prompt.md`](./audit-pr.prompt.md)
 
-**Purpose:** Perform a thorough, opinionated code review of a pull request across 13 comprehensive categories. Acts as a Principal Code Reviewer to identify issues, suggest fixes, and provide actionable feedback ready for human review and posting.
+**Purpose:** Perform a thorough, opinionated code review of a pull request across 13 categories. Produces ready-to-post comments with severity triage and an overall summary for human review.
 
 **Key Features:**
 
 - **3-Step Review Process:**
-    - Step 1: PR Alignment Check (verify PR title, description, linked ticket, diff scope, breaking changes, and PR size)
-    - Step 2: Categorized Code Review (13 review categories covering correctness, security, privacy, performance, testing, and more)
-    - Step 3: Overall Summary (structured verdict with stats, top concerns, and positive callouts)
-- **13 Review Categories:**
-    1. Correctness & Logic
-    2. Security & Vulnerability
-    3. Privacy & Data Protection
-    4. Error Handling & Resilience
-    5. Code Quality & Cleanliness
-    6. Architecture & Design
-    7. Testing
-    8. Performance & Efficiency
-    9. Documentation & Comments
-    10. Standards & Style Consistency
-    11. Accessibility (UI changes only)
-    12. Concurrency & Thread Safety
-    13. Regulatory & Compliance
-- **Severity Triage:** Marks findings as 🔴 Blocking, 🟡 Non-blocking, 🔵 Suggestions, or ✅ Positive callouts
-- **Specific, Actionable Feedback:** Every finding includes file path, line range, issue description, and suggested fix (where applicable)
+    - Step 1: PR Alignment Check (title, description, linked ticket, diff scope, breaking changes, PR size)
+    - Step 2: Categorized Code Review (13 categories — correctness, security, privacy, performance, testing, etc.)
+    - Step 3: Overall Summary (verdict, stats, top concerns, positive callouts)
+- **Severity Triage:** 🔴 Blocking, 🟡 Non-blocking, 🔵 Suggestions, ✅ Positive callouts
+- **Actionable Findings:** Every finding includes file path, line range, issue description, and suggested fix
 
 **When to Use:**
 
 - During pull request reviews (before merge)
 - As a second opinion on code changes
-- To ensure comprehensive coverage of security, privacy, and performance concerns
 - When you need detailed, ready-to-post review comments
 
-**Assumptions:**
-
-- Active GitHub pull request with `#activePullRequest` and `#changes` accessible
-- No external tools required (GitHub/Jira tools are optional and noted as conditional)
-
 ---
 
 ### [`audit-quality.prompt.md`](./audit-quality.prompt.md)
 
-**Purpose:** Perform a deep-dive audit of your codebase to identify architectural flaws, technical debt, and maintainability issues—then automatically implement improvements.
+**Purpose:** Perform a deep-dive audit of your codebase to identify architectural flaws, technical debt, and maintainability issues — then automatically implement improvements.
 
 **Key Features:**
 
-- **Breadth-First Audit:** Analyzes code architecture, design patterns, code health, security, and standards
-- **Test-Driven Implementation:** Applies refactors using a TDD (Test-Driven Development) approach
-- **Automatic Validation:** Runs your project's validation command to ensure changes work
-- **Documentation Sync:** Updates documentation to reflect code changes (Step n-1 before final validation)
-
-**What It Analyzes:**
-
-- Architecture & design patterns (coupling, modularity, over-engineering)
-- Code health (correctness, clarity, cyclomatic complexity, dead code, DRY violations)
-- Robustness & error handling (resilience, idempotency, swallowed errors)
-- Security & privacy concerns
-- Standards & style adherence
-- Accessibility (for UI code)
-- Test quality and coverage
+- **Breadth-First Audit:** Analyzes architecture, code health, security, privacy, performance, and 16 total categories
+- **Proactive Implementation:** Identifies issues and immediately implements fixes
+- **Incremental Validation:** Runs your project's validation command after each change
+- **Documentation Sync:** Updates documentation to reflect code changes
 
 **When to Use:**
 
-- During code review cycles (before PR merge)
 - As part of regular maintenance sprints
 - When tackling technical debt
 - Before major releases (ensure code quality baseline)
 
-**Assumptions:**
-
-- Your project has a test suite (Jest, Cypress, etc.)
-- You have a validation script defined (e.g., `npm run validate`)
-- You follow a specific style guide (defaults to Google Style Guide)
-
 ---
 
 ## Prerequisites

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

@@ -21,6 +21,8 @@ The portfolio uses Next.js App Router, where file names in [src/app/](../../src/
 
 ```mermaid
 flowchart TD
+    accTitle: App Router Component Hierarchy
+    accDescr: Layout wraps all routes and provides metadata, includes GeneralLayout which contains Navbar, Footer, StarsBackground and CookieSnackbar. Page renders Banner, ProjectsGrid, and Publications
     Layout[layout.tsx] -->|Wraps| Page[page.tsx]
     Layout -->|Provides| Metadata[SEO & Metadata]
     Layout -->|Includes| GL[GeneralLayout]

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

@@ -69,6 +69,8 @@ Implementation: [src/components/banner/Avatar.tsx](../../src/components/banner/A
 
 ```mermaid
 sequenceDiagram
+    accTitle: Avatar Sneeze and Easter Egg Interaction Sequence
+    accDescr: User hovers avatar on 5th time triggering sneeze animation and logging event. On 30th time (6th sneeze), aaaahhhh helper is called to transform page and log event
     participant User
     participant Avatar
     participant Helper

.github/prompts/readme.md

@@ -12,6 +12,8 @@ The CookieSnackbar component displays a cookie consent notification to users whe
 
 ```mermaid
 flowchart TD
+    accTitle: Cookie Snackbar State Management
+    accDescr: CookieSnackbar checks if browser cookie is set. If not set, shows notification and expires in 1 year. If set, hides notification
     CookieSnackbar[CookieSnackbar] -->|Checks| Cookie[Browser Cookie]
     Cookie -->|Not Set| Show[Show Notification]
     Cookie -->|Set| Hide[Hide Notification]
@@ -69,6 +71,8 @@ const handleClose = () => {
 
 ```mermaid
 sequenceDiagram
+    accTitle: Cookie Consent Component Sequence
+    accDescr: When user visits site, component mounts on client and checks document cookie. If cookie exists, notification is hidden. If not, it shows notification and sets cookie after 1 second, or user can click close
     participant User
     participant Component
     participant Browser

docs/architecture/app-directory.md

@@ -19,6 +19,8 @@ This document describes the internal architecture, relationships, and usage of m
 
 ```mermaid
 flowchart TD
+    accTitle: Page Component Composition Tree
+    accDescr: Root Layout wraps Navbar, Main Content, Footer, and ServiceWorkerRegister. Main Content contains Banner, ProjectsGrid, Publications, StarsBackground, CookieSnackbar. Banner contains Avatar. ProjectsGrid and Publications generate cards. Footer contains social links
     RootLayout[Root Layout] --> Navbar
     RootLayout --> Main[Main Content]
     RootLayout --> Footer
@@ -186,6 +188,8 @@ Data flow:
 
 ```mermaid
 sequenceDiagram
+    accTitle: Page Data Integration and Analytics Flow
+    accDescr: Page imports projects, publications, socials from data. Data is passed as props to components. Components render UI and log analytics events to Firebase
     participant Page
     participant Data
     participant Component
@@ -231,6 +235,8 @@ sequenceDiagram
 
 ```mermaid
 flowchart LR
+    accTitle: Component Data and Event Flow
+    accDescr: Data is imported from src/data into page.tsx. Page passes data as props to ProjectsGrid, Publications, Footer, Navbar and Avatar. All components log events to Firebase
     Data[src/data/] -->|Import| Page[page.tsx]
     Page -->|Props| ProjectsGrid
     Page -->|Props| Publications

docs/architecture/components/avatar.md

@@ -10,14 +10,18 @@ The Navbar component is a fixed-position navigation bar located in [`src/compone
 
 ```mermaid
 flowchart LR
+    accTitle: Navbar Navigation Structure
+    accDescr: Navbar contains Home button and links for Projects, Publications, Socials, and Resume. Each item scrolls to or opens its target section or PDF
     Navbar[Navbar] -->|Contains| Home[Home Button]
     Navbar -->|Contains| Projects[Projects Link]
     Navbar -->|Contains| Pubs[Publications Link]
+    Navbar -->|Contains| Socials[Socials Link]
     Navbar -->|Contains| Resume[Resume Link]
 
     Home -->|Scroll to| Top[Page Top]
     Projects -->|Scroll to| ProjectsGrid[Projects Grid]
     Pubs -->|Scroll to| PublicationsList[Publications]
+    Socials -->|Scroll to| Footer[Footer / Socials]
     Resume -->|Opens| PDF[Resume PDF]
 ```
 
@@ -57,6 +61,7 @@ logAnalyticsEvent('navbar_home', {
 - `navbar_home` - Home button click
 - `navbar_projects` - Projects link click
 - `navbar_publications` - Publications link click
+- `navbar_socials` - Socials link click
 - `navbar_resume` - Resume link click
 
 ### 3. Responsive Design
@@ -121,6 +126,18 @@ if (pathname === '/') {
 **Target:** `#publications` section
 **Text:** "Publications"
 
+### Socials Link
+
+**Icon:** Profile picture (drawn avatar)
+**Target:** `#socials` section (Footer)
+**Behavior:** Displays a small profile image that links to the social media links in the footer
+
+```tsx
+<Link aria-label='See socials' href='/#socials'>
+	<Image alt='Logo' height={24} src='/images/drawn/profile_pic_drawn.webp' width={24} />
+</Link>
+```
+
 ### Resume Link
 
 **Target:** External PDF (`/resume/resume.pdf`)
@@ -147,6 +164,8 @@ if (pathname === '/') {
 
 ```mermaid
 sequenceDiagram
+    accTitle: Navbar Navigation Interaction Sequence
+    accDescr: User clicks navbar items. Navbar logs events, checks pathname, then either smooth scrolls on home page or navigates to hash on other pages. Shows both Projects and Socials click flows
     participant User
     participant Navbar
     participant Router
@@ -164,6 +183,18 @@ sequenceDiagram
         Navbar->>Router: Navigate to /#projects-grid
         Router->>DOM: Scroll to section
     end
+
+    User->>Navbar: Click Socials
+    Navbar->>Analytics: Log event
+    Navbar->>Router: Check pathname
+
+    alt On Home Page
+        Navbar->>DOM: getElementById('socials')
+        DOM->>DOM: scrollIntoView({behavior: 'smooth'})
+    else On Other Page
+        Navbar->>Router: Navigate to /#socials
+        Router->>DOM: Scroll to section
+    end
 ```
 
 ## Accessibility Features

docs/architecture/components/cookie-snackbar.md

@@ -22,6 +22,8 @@ The projects grid is displayed using the `ProjectsGrid` component located in [Pr
 
 ```mermaid
 flowchart LR
+    accTitle: Projects Grid Data Flow
+    accDescr: ProjectsGrid component fetches projects data, maps to grid items, displays project cards with thumbnail image, name, title/employer, and action links. Includes network-aware video autoplay
     A[ProjectsGrid Component] -->|Fetches| B[Projects Data]
     B --> C[Maps Projects to Grid Items]
     C --> D[Displays Project Cards]