skill doc sync

Writing Community

Skill notes

Caps

Max 30 doc files scanned — skip files beyond the cap, warn the user Never clobber CHANGELOG — append only, never delete existing entries Ask user before changing narrative/philosophy sections — risky changes require confirmation

Step 1: Discover Docs

Find all .md files in the project root (max depth 2), skipping node_modules/ and .git/. Read each discovered doc file so you have their current content in context.

Step 2: Cross-Reference Diff

Run git diff --stat HEAD~1 (or diff against the base branch if on a feature branch) to identify which files changed and what content may now be stale in each doc. For each doc file, check whether any paths, function names, counts, or version numbers mentioned in the doc were affected by the diff.

Step 3: Auto-Update Factual Corrections

Fix paths, counts, table entries, and version numbers automatically. These are mechanical changes that do not alter meaning. Auto-update targets: File paths that were renamed or moved in the diff Numeric counts (e.g., "42 tests" when the number changed) Version strings (e.g., v9.5.0 when package.json bumped)

Step 4: Risky Change Detection

Flag narrative, philosophy, or security-related doc sections for user confirmation. Do NOT auto-edit these. Risky categories (require user approval): Sections with headings containing: "Philosophy", "Principles", "Vision", "Mission", "Security", "Threat Model", "Architecture Decision" Paragraphs that express opinion, strategy, or rationale (not just facts) Content under ## Why or ## Rationale headings

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Writing
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@nyldn · no license declared
Token usage
Lean
Setup complexity
Manual integration
External API key
Not required
Operating systems
Docker
Runtime requirements
Docker
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Discover Docs

Find all `.md` files in the project root (max depth 2), skipping `node_modules/` and `.git/`. Read each discovered doc file so you have their current content in context.

02
Step 2: Cross-Reference Diff

Run `git diff --stat HEAD~1` (or diff against the base branch if on a feature branch) to identify which files changed and what content may now be stale in each doc. For each doc file, check whether any paths, function names, counts, or version numbers mentioned in the doc were affected by the diff.

03
Step 3: Auto-Update Factual Corrections

Fix paths, counts, table entries, and version numbers automatically. These are mechanical changes that do not alter meaning. Auto-update targets: File paths that were renamed or moved in the diff Numeric counts (e.g., "42 tests" when the number changed) Version strings (e.g., `v9.5.0` when `package.json` bumped)

04
Step 4: Risky Change Detection

Flag narrative, philosophy, or security-related doc sections for user confirmation. Do NOT auto-edit these. Risky categories (require user approval): Sections with headings containing: "Philosophy", "Principles", "Vision", "Mission", "Security", "Threat Model", "Architecture Decision" Paragraphs that express opinion, strategy, or rationale (not just facts) Content under `## Why` or `## Rationale` headings

05
Step 5: CHANGELOG Voice Polish

Apply the "sell test" to every CHANGELOG entry: "Would a user reading this bullet think 'oh nice, I want to try that'?" Rules: Lead with the user benefit, not the implementation detail Use active voice ("Add X" not "X was added") Keep bullets under 120 characters

06
Step 6: Cross-Doc Consistency

Check that key values are aligned across all documentation files. Consistency checks: Version numbers match across `README.md`, `CLAUDE.md`, `package.json`, `CHANGELOG.md`, and any other files referencing the current version Feature lists in README match what is actually implemented (cross-reference with command/skill directories) Badge URLs and shield.io references are up to date

07
Step 7: Discoverability Check

Ensure every documentation file is reachable from `README.md` or `CLAUDE.md`. Orphaned docs are invisible docs. Check: Every `.md` file in the project should be linked from either `README.md` or `CLAUDE.md` (directly or transitively through another linked doc) Flag orphaned docs that have no inbound links Suggest where to add links for orphaned docs

08
Step 8: TODOS.md Update

Update the project's task tracking based on the diff. Actions: Mark completed items: scan TODO/FIXME/HACK comments that were removed in the diff and mark corresponding items as done Flag new deferred work: scan TODO/FIXME/HACK comments that were added in the diff and create new tracking entries Update completion percentages if the project uses progress tracking

09
Step 9: Commit Doc Changes

Commit all documentation changes to the current branch and update the PR body with a doc-sync summary. If a PR exists for the current branch, update its body to include a doc-sync section:

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.