playbooks

home / skills / tom555my / dev-kit / dev-kit-refine

dev-kit-refine skill

/.claude/skills/dev-kit-refine

This skill updates and consolidates .dev-kit/docs and .dev-kit/knowledge by validating against the codebase and generating a change report.

npx playbooks add skill tom555my/dev-kit --skill dev-kit-refine

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.5 KB
---
name: dev-kit-refine
description: "Consolidate and update documentation in `.dev-kit/docs/` and `.dev-kit/knowledge/` by verifying against the codebase. Use when: documentation has drifted from implementation; consolidating duplicate content; updating docs after major refactoring; verifying documentation accuracy."
---

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.

<user-request>
 $ARGUMENTS
</user-request>

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

FAQ

Does the skill edit files outside .dev-kit/docs/ and .dev-kit/knowledge/?

No. It only edits files under .dev-kit/docs/ and .dev-kit/knowledge/ and writes the single report file under .dev-kit/docs/reports/.

What goes into the generated report?

The report includes a summary of high-level changes, a list of updated files with brief notes, unresolved discrepancies that need human follow-up, and recommended next actions or tickets.