dev-kit-refine_skill

Overview

This skill consolidates and updates documentation under .dev-kit/docs/ and .dev-kit/knowledge/ by verifying text against the current codebase and producing a dated report of changes. It edits only those folders in place, removes duplicates, and creates a single report file summarizing updates and outstanding discrepancies. Use it to bring developer-facing docs back into sync with implementation after refactors or drift.

How this skill works

The skill inventories all markdown files in the two target folders, scans the codebase to build an evidence map (routes, APIs, schemas, configs, UI patterns), and compares documentation claims to that evidence. It consolidates overlapping content, applies minimal in-place edits for accuracy and tone, and writes a report at .dev-kit/docs/reports/DOC_KIT_REFINE_REPORT_YYYY-MM-DD.md detailing changes, unresolved issues, and follow-ups.

When to use it

• Documentation has drifted from the implementation after refactoring
• Multiple docs duplicate the same guidance and need consolidation
• Preparing a release or onboarding where docs must match code behavior
• Auditing docs for accuracy before public or internal handoff

Best practices

• Run the skill with an explicit focus parameter to limit scope (e.g., "auth" or "routing") when making targeted changes
• Keep edits minimal and fact-based; avoid adding new conceptual content unless verified in code
• Consolidate duplicates into a canonical file and update internal links to that canonical location
• Document unresolved contradictions in the report and add clear follow-up action items
• Preserve existing doc style and formatting conventions for consistency

Example use cases

• After a major refactor renaming routes, update README snippets, API reference, and link targets under .dev-kit/docs/
• Merge three separate how-to guides about configuration into a single canonical guide and update references
• Verify authentication docs match current auth middleware and surface missing config options in the report
• Run a focused pass on "routing" docs before a release to ensure routes and examples are accurate