Merge pull request #4 from raychrisgdp/docs-links-guard

chore(docs): add documentation links and improve code formatting

Author: raychrisgdp

.cursor/commands/pr-desc.md

@@ -6,10 +6,10 @@ Generate or update `PR_DESCRIPTION.md` so it reflects the current diff against t
 
 For combined work across the backend API, CLI, and data models—call out each surface area's feature set, integration touchpoints, and manual verification steps independently so reviewers understand the scope split.
 
-**IMPORTANT - Title vs Description Separation**:
-- The PR **title** is stored separately and used for the GitHub PR `title` field (Conventional Commit format: `type(scope): description`)
-- The PR **description** body starts with `## Summary` (NOT `# Title`) and is used for the GitHub PR `body` field
-- When updating GitHub PRs, ensure the title does NOT appear as a markdown heading in the description body to avoid duplication
+**IMPORTANT - Title Format**:
+- The PR **title** is included as a `# Title` heading at the top of `PR_DESCRIPTION.md` (Conventional Commit format: `type(scope): description`)
+- The PR **description** body starts with `## Summary` after the title heading
+- When updating GitHub PRs, extract the title from the first line (`# Title`) and use it for the PR `title` field, and use the rest of the content (starting from `## Summary`) for the PR `body` field
 
 **GitHub PR Sync**:
 - After generating/updating `PR_DESCRIPTION.md` locally, the command will detect if there's an open PR for the current branch
@@ -184,18 +184,18 @@ Based on the file analysis from Step 2, automatically determine which testing ap
    - Custom notes under **Additional Notes** are preserved unless clearly obsolete.
    - Previous manual edits provided via $ARGUMENTS are respected.
 3. Overwrite (or create) `PR_DESCRIPTION.md` with the following sections, in template order, incorporating any human-provided clarification answers into the relevant sections and removing resolved `Clarification Needed` items.
-   - **CRITICAL**: The file should start with `## Summary` (not `# Title`). The title is stored separately and should NOT appear as a markdown heading in the description body.
-   - When updating GitHub PRs, use the title for the PR `title` field and the description content (starting from `## Summary`) for the PR `body` field.
+   - **CRITICAL**: The file should start with `# Title` as a markdown heading, followed by `## Summary`. The title is included as the first line of the file.
+   - When updating GitHub PRs, extract the title from the first line (`# Title`) and use it for the PR `title` field, and use the rest of the content (starting from `## Summary`) for the PR `body` field.
 
 ### Title
 
-- **IMPORTANT**: The title is separate from the description body. Generate ONLY the title text (no markdown heading, no `#` prefix).
+- **IMPORTANT**: The title is included as a `# Title` markdown heading at the top of `PR_DESCRIPTION.md`.
 - Provide a Conventional Commit-style title (`type(scope): description`) following the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification. Derive the subject from the current diff and `.github/pull_request_template.md`, not from any previously generated `PR_DESCRIPTION.md`.
 - **Analyze the diff to determine the primary change type**: Use the file changes and modifications to identify if this is a `feat`, `fix`, `refactor`, `test`, `docs`, etc.
 - **Scope identification**: Look at which components were most heavily modified to determine the scope (e.g., `api`, `cli`, `models`, `services`, `docs`).
 - **Description synthesis**: Based on the actual changes observed in the diff, create a concise description that captures the essence of what was modified.
 - **User clarification**: If the primary purpose isn't clear from the diff analysis, ask the user to clarify the main objective of these changes.
-- **Store separately**: Save the title as a separate variable/field. When updating GitHub PRs, use the title for the `title` parameter and the description body (without title heading) for the `body` parameter.
+- **Format**: Write the title as `# type(scope): description` at the very beginning of `PR_DESCRIPTION.md`, followed by a blank line, then `## Summary`.
 
 ### Summary
 
@@ -298,10 +298,10 @@ Based on the file analysis from Step 2, automatically determine which testing ap
    - Merge new review areas/testing steps with existing ones, de-duplicating while keeping stable ordering (stable = by file path).
    - Retain any user-edited checklist states unless contradicted by automated checks.
 3. Save the file at the repository root: `$REPO_ROOT/PR_DESCRIPTION.md`.
-   - **File format**: The file should start directly with `## Summary` (no title heading). Store the title separately.
+   - **File format**: The file should start with `# Title` as a markdown heading, followed by a blank line, then `## Summary`.
    - **GitHub PR updates**: When updating GitHub PRs via API, use:
-     - `title`: The Conventional Commit-style title (e.g., `docs: restructure documentation and improve code quality`)
-     - `body`: The full content from `PR_DESCRIPTION.md` starting from `## Summary` (do NOT include the title as a heading)
+     - `title`: Extract the title from the first line of `PR_DESCRIPTION.md` by removing the `# ` prefix (e.g., if file starts with `# docs: restructure documentation`, use `docs: restructure documentation`)
+     - `body`: The full content from `PR_DESCRIPTION.md` starting from `## Summary` (do NOT include the title heading)
 4. Print (or log) a short status summary for the user including: title string, number of files changed, and whether the checklist sync item is checked.
 
 5. **GitHub PR Sync (Optional)**:
@@ -312,16 +312,14 @@ Based on the file analysis from Step 2, automatically determine which testing ap
      - Find a PR where the head branch matches the current branch (check `head.ref` field)
    - **Prompt user**: If an open PR is found, ask the user: "Found open PR #X for branch 'Y'. Would you like to update the PR title and description on GitHub with the generated content? (yes/no)"
    - **Update PR if confirmed**: If the user confirms "yes" (or if `$ARGUMENTS` contains `--sync` or `--update-pr`):
-     - **Extract title**:
-       - First, check if `PR_TITLE.txt` exists and read from it
-       - If not, generate the title using the same logic from step 3 (Conventional Commit format based on diff analysis)
-     - **Extract description**: Read the full content from `PR_DESCRIPTION.md` (it should start with `## Summary`, not `# Title`)
+     - **Extract title**: Read the first line of `PR_DESCRIPTION.md` (should be `# type(scope): description`) and remove the `# ` prefix to get the title
+     - **Extract description**: Read the full content from `PR_DESCRIPTION.md` starting from `## Summary` (skip the title heading and blank line)
      - **Update PR**: Use GitHub MCP `update_pull_request` tool with:
        - `owner`: Repository owner
        - `repo`: Repository name  
        - `pullNumber`: The PR number found
-       - `title`: The Conventional Commit-style title (without markdown formatting)
-       - `body`: The full content from `PR_DESCRIPTION.md` (starting from `## Summary`, ensuring no title heading is included)
+       - `title`: The Conventional Commit-style title extracted from the first line (without the `# ` markdown heading prefix)
+       - `body`: The full content from `PR_DESCRIPTION.md` starting from `## Summary` (do NOT include the title heading)
      - **Print confirmation**: "✓ Updated PR #X on GitHub: title and description synced"
    - **Skip if no PR found**: If no open PR is found, print: "No open PR found for current branch. PR description saved locally in `PR_DESCRIPTION.md`. You can create a PR or update manually later."
    - **Skip if user declines**: If user declines or answers "no", print: "PR description saved locally in `PR_DESCRIPTION.md`. You can update the PR manually when ready."

.cursor/commands/review-implement.md

@@ -0,0 +1,101 @@
+# Review Implement Command (personal-todo)
+
+Read a validated review report and implement actionable findings, prioritizing Critical and High severity items with clear implementation paths.
+
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+## Goal
+
+After a review has been validated via `/review-validate`, implement the remaining actionable findings from the review report. Focus on Critical and High priority items that have clear implementation paths, and update the review file so it reflects the current state using the same format as `.cursor/commands/review.md`.
+
+**Note**: This command can be used alongside manual fixes. The author may choose to fix issues manually or use this command to automate implementation.
+
+## Execution Steps
+
+1. **Select Target Review File**
+   - If the user supplies a path, use it.
+   - Otherwise, pick the most recent `reviews/REVIEW_*.md` file. **Hard error**: If no review file found, fail with clear error message.
+
+2. **Parse & Filter Findings**
+   - Read the review file and extract: Review Summary, Metrics, and Findings grouped by severity.
+   - **Include**: Critical and High severity findings with `file:line` references and explicit "Change:" recommendations.
+   - **Exclude**: Findings marked as "Out of scope", "Deferred", or requiring external clarification ("NEEDS CLARIFICATION").
+   - **Exclude**: Findings related to `PR_DESCRIPTION.md` (this file is for PR authoring and should not be modified).
+   - **User Override**: If `$ARGUMENTS` contains specific finding IDs (e.g., `--findings Spec-1`), implement only those.
+
+3. **Prioritize & Implement**
+   - **Order**: Phase 1 (Critical: security, correctness), Phase 2 (High: maintainability, performance), Phase 3 (Medium: if requested).
+   - **Execution**: For each actionable finding:
+     - Read target file + context (10 lines before/after).
+     - Apply change exactly as recommended (No over-engineering).
+     - Follow project conventions (FastAPI, SQLAlchemy, Pydantic).
+     - Validate using finding's "Validate:" clause.
+     - Update review file immediately to track progress.
+
+4. **Run Global Validation**
+   - After implementations:
+     - Run spec validation: `uv run python scripts/check_docs.py` (if specs touched).
+     - Run linting: `uv run ruff check` on modified files.
+     - Run tests: Execute relevant `pytest` commands.
+
+5. **Generate Summary**
+   - Output summary of implemented findings, skipped findings, and modified files.
+
+## Implementation Directives
+
+**Directive I: Standard Adherence**
+- **Follow Conventions**: Use existing code style, absolute imports, and naming conventions.
+- **Preserve Behavior**: Only modify code explicitly specified in the "Change:" recommendation.
+- **No Over-Engineering**: Implement exactly what is recommended, no more.
+
+**Directive II: Incremental Verification**
+- **Atomic Progress**: Remove resolved findings immediately after successful implementation.
+- **Verification**: Run all validation commands mentioned in the finding's "Validate:" clause.
+- **Documentation**: Update docstrings/comments if the change affects public APIs.
+
+## Finding Format Parsing
+
+Parse findings using the same format as `/review`:
+
+```
+[ID][Severity][Tag] file:line – description
+
+**Current Implementation:** (code snippet)
+
+**Problem:** explanation
+
+**Change:** recommendation with code example
+
+**Validate:** test file or command
+```
+
+Extract:
+- Finding ID (e.g., `Spec-1`, `Quality-2`)
+- Severity (Critical, High, Medium, Low)
+- File path and line number
+- Change recommendation (code example or clear steps)
+- Validation command (if provided)
+
+## Output Format
+
+After implementation, display:
+```markdown
+## Implementation Summary
+✅ Implemented: N findings ([Spec-1], [Quality-2])
+⏭️  Skipped: M findings (Reason)
+❌ Failed: K findings (Error: message)
+📝 Files Modified: file1.py, file2.py
+🔍 Validation: Spec [Passed], Linting [Passed], Tests [Failed (Notes)]
+```
+
+## Integration with Review Workflow
+
+This command is used after `/post-review` when author chooses to automate fixes.
+
+Context: $ARGUMENTS

.cursor/commands/review-validate.md

@@ -0,0 +1,54 @@
+# Review Validate Command (personal-todo)
+
+Validate current specs after a review and refresh the existing review report to match the current state.
+
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+## Goal
+
+After a review report exists in `reviews/`, re-check the current state, validate specs, and update that review file using the same format defined in `.cursor/commands/review.md`.
+
+## Execution Steps
+
+1. **Select Target Review File**
+   - If the user supplies a path, use it.
+   - Otherwise, pick the most recent `reviews/REVIEW_*.md`.
+2. **Capture Baseline**
+   - **Ensure `main` is up-to-date**: `git fetch origin main:main` (if exists) or `git fetch origin main`.
+   - Record `git branch --show-current`, `git rev-parse main`, `git merge-base main HEAD`, and `git diff --stat main...HEAD`.
+3. **Validate State**
+   - Run `uv run python scripts/check_docs.py` for spec integrity.
+   - If validation fails, capture errors as new findings.
+4. **Re-evaluate Findings**
+   - Compare the current repo state to the review file contents.
+   - Remove or downgrade findings that no longer apply.
+   - Add new findings based on the current diff/state, using deterministic IDs that continue existing sequences.
+   - **Ignore `PR_DESCRIPTION.md`**: Do not flag issues in `PR_DESCRIPTION.md`; it is for PR authoring purposes only.
+5. **Update Review Report**
+   - Keep the same template and formatting as `.cursor/commands/review.md`.
+   - Update **Executive Summary**, **Findings**, **Strengths**, **Testing Results**, and **Metrics Summary**.
+   - If no findings remain, set Decision to approve and Key Recommendations to “None”.
+   - Keep deterministic IDs (`[Spec-1]`, `[Quality-2]`, etc.).
+6. **Write Changes In-Place**
+   - Update the existing `reviews/REVIEW_*.md` file only; do not create a new review report.
+
+## Output Directives (CRITICAL)
+
+**Directive I: Report Integrity**
+- **Clean Output**: Never include "[N tools called]" lines or internal implementation details.
+- **Actual Commands**: The Testing Results section must show the actual commands run (e.g., `uv run ruff check .`) and their output.
+- **Explicit Skips**: List any skipped validations with reasons (e.g., "⏭️ Skipped: [command] - Reason: [reason]").
+
+**Directive II: Structural Stability**
+- **Template Compliance**: Do not add extra sections beyond the review template; keep the report layout stable.
+- **No Tool Names**: Do not reference any tool names in the report; keep the output consistent with existing review files.
+
+## Integration with Review Workflow
+
+This command runs after `/review` (both initial and re-reviews) to validate findings before posting to GitHub.