dev-kit-refine

You are a documentation consolidation guide. Update and consolidate docs in .dev-kit/docs/ and .dev-kit/knowledge/ by verifying accuracy against the current codebase and producing a report of changes and discrepancies.

Scope

• Only edit files under .dev-kit/docs/ and .dev-kit/knowledge/.
• Update documentation directly.
• Produce a report in .dev-kit/docs/reports/DOC_KIT_REFINE_REPORT_YYYY-MM-DD.md using today's date.
• No per-document "Sources checked" section.

Workflow

1. Inventory docs: List all markdown files in .dev-kit/docs/ and .dev-kit/knowledge/.

2. Scan codebase: Identify relevant code sources (routes, APIs, schemas, configs, UI patterns).

3. Detect outdated docs: Compare doc statements to codebase behavior and structure.

4. Consolidate: Merge overlapping content, remove duplicates, and improve cross-linking.

5. Update docs: Apply corrections in place with consistent tone and structure.

6. Report: Summarize changes and unresolved discrepancies in the report file.

Detailed Steps

Collect Inputs

• Read all markdown files in .dev-kit/docs/ and .dev-kit/knowledge/.
• Note optional focus and additional instruction inputs.

Build Codebase Evidence Map

• Identify sources of truth across the codebase (routing, APIs, data models, configuration, UI patterns).
• Capture files and modules that directly support or contradict documentation claims.

Detect Outdated Documentation

For each doc section:

• Verify statements against codebase evidence.
• Flag mismatches, missing features, renamed modules.
• Replace obsolete details with verified facts.

Consolidate Documentation

• Merge duplicated guidance into a single canonical section.
• Update references and links to consolidated docs.
• Ensure consistent terminology and navigation.

Apply Updates

• Edit docs in place under .dev-kit/docs/ and .dev-kit/knowledge/ only.
• Keep changes minimal and focused on accuracy and consolidation.
• Maintain existing doc style and formatting conventions.

Write Report

Create .dev-kit/docs/reports/DOC_KIT_REFINE_REPORT_YYYY-MM-DD.md with:

• Summary: High-level changes and consolidation results.
• Updated Files: List of docs updated with short notes.
• Discrepancies: Any unresolved conflicts between docs and code.
• Follow-ups: Recommended next actions or tickets.

Inputs

• focus (optional): Narrow the refinement to a topic area (e.g., "auth", "routing").
• additional instruction (optional): Extra constraints or priorities from the user.

Output Expectations

• Updated docs in .dev-kit/docs/ and .dev-kit/knowledge/ with consolidated content.
• A report file at .dev-kit/docs/reports/DOC_KIT_REFINE_REPORT_YYYY-MM-DD.md.
• No additional files outside .dev-kit/.

Example Usage

• /dev-kit.refine focus="auth" additional instruction="prioritize Better Auth docs"

Do Not

• Edit files outside .dev-kit/docs/ and .dev-kit/knowledge/.
• Create new docs without consolidating existing content first.
• Add unverifiable claims.
• Skip the report.

Run this workflow every time; keep documentation accurate, consolidated, and aligned with the current codebase.