Skill: Check Documentation Consistency

<role_gate> <required_agent>Librarian</required_agent> <instruction> Before proceeding with any instructions, you MUST strictly check that your ACTIVE_AGENT_ID matches the required_agent above.

Match Case:

• •Proceed normally.

Mismatch Case:

• •You MUST read the file .github/agents/{required_agent}.agent.md.
• •You MUST ADOPT the persona defined in that file for the duration of this skill.
• •Proceed with the skill acting as the {required_agent}.

You are supporting the @Librarian. Your goal is to verify the consistency of all documentation starting from the project's README.md, and propose or implement necessary corrections.

📋 Task Initialization

IMMEDIATELY use the #todo tool to register the following tasks to track your progress:

1. •Read Documentation: Read project root README.md and agent docs.
2. •Verify Links: Check file paths, relative links, and navigability from root.
3. •Verify Content Consistency: Check directory structure, tech stack, and code references.
4. •Verify Onboarding: Check flow from Setup -> Build -> Usage -> Architecture.
5. •Generate Report: Create a summary of findings (Pass/Warning/Error).
6. •Propose/Implement Fixes: Auto-fix simple issues, propose complex ones.
7. •Final Check: Review the "Final Check" section.

🎯 Objective

Ensure that:

1. •Structure is Complete: The project root README.md acts as a proper entry point and all links work.
2. •Content is Consistent: Documentation matches the actual codebase (files, classes, configs).
3. •DRY Principle is Followed: Information is not duplicated unnecessarily.
4. •Project Rules are Met: Documentation follows docs/ structure and other project conventions.
5. •Navigability is Complete: All documents are reachable starting from the project root README.md.
6. •Onboarding is Smooth: New users can easily find Setup, Build, Usage, and Architecture info.

🛠️ Execution Steps

Step 1: Read Documentation

1. •

   Read Entry Point:

   • •Read the project root README.md.
   • •Identify key sections and links to other documents.
2. •

   Read Agent Documentation:

   • •List files in docs/.
   • •Read key documents like docs/architecture/directory-structure.md, docs/architecture/tech-stack.md, and docs/architecture/key-flows.md.

Step 2: Verify Links and Navigability

1. •

   Extract Links:

   • •Identify all file paths and relative links in the read documents.
2. •

   Verify Existence:

   • •Verify that linked files and directories actually exist.
   • •Check for broken images or dead links.
3. •

   Check Reachability:

   • •Ensure every documentation file is reachable by following links starting from the project root README.md.
   • •Identify "orphan" documents that exists but are not linked.

Step 3: Verify Content Consistency

1. •

   Directory Structure:

   • •Compare docs/architecture/directory-structure.md with the actual directory structure of the project root and key subdirectories.
   • •Note any missing or obsolete directories in the documentation.
2. •

   Tech Stack & Config:

   • •Compare docs/architecture/tech-stack.md with pyproject.toml, package.json, or other configuration files.
   • •Ensure versions and dependencies match.
3. •

   Code References:

   • •If documents mention specific classes or functions, confirm they still exist and are named correctly.
4. •

   Onboarding Flow:

   • •Verify that a new user can smoothly follow the path: Environment Setup -> Build/Run -> Usage -> Architecture.
   • •Ensure these sections are clearly visible and logically ordered.

Step 4: Report and Fix

1. •

   Generate Report:

   • •Create a summary of findings categorized by:
     • •✅ Pass: Items that are consistent.
     • •⚠️ Warning: Minor inconsistencies or potential issues.
     • •❌ Error: Broken links, missing files, or major contradictions.
2. •

   Propose/Implement Fixes:

   • •Auto-Fix: For simple issues like typos or broken relative paths, fix them immediately.
   • •Proposal: For structural changes or missing content, describe the recommended changes in the report.

📤 Output Format

Present your findings in the following format:

# Documentation Consistency Report

## Summary

[Brief summary of the overall state of documentation]

## Findings

### ✅ Consistent Items

- README.md links are valid.
- ...

### ❌ Issues Found

- **Broken Link**: `README.md` refers to `docs/setup.md` which does not exist.
- **Outdated Content**: `directory-structure.md` misses the new `services/payment` directory.

## Actions Taken

- Fixed typo in `README.md`.

## Recommendations

- Update `directory-structure.md` to include `services/payment`.

✅ Final Check

Before finishing, confirm:

• • All todo are marked as completed.
• • All broken links are reported or fixed.
• • Navigability from project root README.md is confirmed.
• • Onboarding flow (Setup->Build->Usage->Architecture) is verified.
• • Consistency report is generated in the correct format.
• • Proposed fixes are actionable.