From ca39b8074c872df834e37141e58ff95bfdd54abf Mon Sep 17 00:00:00 2001 From: Wayland Date: Tue, 21 Jul 2026 16:23:58 +0200 Subject: [PATCH] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20Make=20/docs:sync-docs=20w?= =?UTF-8?q?indow=20days-based=20by=20default?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change the /docs:sync-docs argument semantics so the lookback window is measured in days by default instead of commits: - `/docs:sync-docs` → last 1 day (default) - `/docs:sync-docs 3` → last 3 days (bare number = days) - `/docs:sync-docs 10 commits` → last 10 commits (explicit keyword only) Rewrite step 1 for the three cases, switch days mode to `git log --since="N days ago"`, keep `git log -N` for commits mode, sweep every commits/-N/number_of_commits reference for consistency, and add an empty-window guard ("no commits in the last N days, nothing to sync"). Bump docs plugin to 1.2.0 (minor: arg-semantics change) and update the plugin-catalog page (Usage, Parameters, examples, tips) to match. Co-Authored-By: Wayland Co-Authored-By: Claude Opus 4.8 --- docs/plugin-catalog/docs-plugin.md | 37 +++++++++++--------- plugins/docs/.claude-plugin/plugin.json | 2 +- plugins/docs/commands/sync-docs.md | 45 +++++++++++++++---------- 3 files changed, 51 insertions(+), 33 deletions(-) diff --git a/docs/plugin-catalog/docs-plugin.md b/docs/plugin-catalog/docs-plugin.md index 510b1e4..75b5f09 100644 --- a/docs/plugin-catalog/docs-plugin.md +++ b/docs/plugin-catalog/docs-plugin.md @@ -6,7 +6,7 @@ **Author:** Flop (flopspm@gmail.com) -**Version:** 1.1.1 +**Version:** 1.2.0 **Keywords:** documentation, sync, git, automation @@ -105,28 +105,35 @@ yes ## Sync Documentation -**Command:** `/docs:sync-docs [number_of_commits]` +**Command:** `/docs:sync-docs [days | N commits]` -Analyzes recent git commits and updates documentation to reflect code changes. +Analyzes recent git changes and updates documentation to reflect code changes. The lookback window is measured in **days by default**; commit-count mode is opt-in via the explicit `commits` keyword. ### Usage ```bash -# Analyze last 5 commits (default) +# Analyze the last 1 day (default) /docs:sync-docs -# Analyze specific number of commits -/docs:sync-docs 10 -/docs:sync-docs 20 +# Analyze a specific number of days (bare number = days) +/docs:sync-docs 3 +/docs:sync-docs 7 + +# Analyze a specific number of commits (explicit `commits` keyword) +/docs:sync-docs 10 commits +/docs:sync-docs 1 commit ``` ### Parameters -- `number_of_commits` (optional): Number of recent commits to analyze. Default: 5 +- `days` (optional, default): A bare number is interpreted as a number of days to look back. Default: **1 day** when no argument is given. +- `N commits` (optional): A number followed by the `commits` (or `commit`) keyword switches to commit-count mode and analyzes exactly that many commits. + +If the resolved window contains no commits (e.g., an empty time range in days mode, or an invalid window), the command reports `"no commits in the last N days, nothing to sync"` and makes no changes. ### What it does -1. Extracts the specified number of recent commits from git history +1. Parses the argument to resolve the lookback window — days by default, or a commit count when the `commits` keyword is used 2. Analyzes commit messages and full diffs to understand changes 3. Reads the current state of all modified files 4. Identifies the documentation folder automatically @@ -148,12 +155,12 @@ git commit -m "Add authentication middleware" git commit -m "Update API endpoints" git commit -m "Refactor database connection" -# Sync documentation with the last 3 commits +# Sync documentation with the last 3 days of changes /docs:sync-docs 3 # Claude analyzes changes and updates relevant docs # Example output: -# "Updated documentation based on 3 recent commits: +# "Updated documentation based on commits from the last 3 days: # - api-reference.md: Added new /auth endpoints # - architecture.md: Updated authentication flow diagram # - getting-started.md: Added authentication setup steps" @@ -162,7 +169,7 @@ git commit -m "Refactor database connection" ### Best Practices - Run after completing a feature or significant change -- Use higher commit counts (10-20) for major refactors +- Use a wider window (e.g. `7` days, or `20 commits`) for major refactors - Review the changes to ensure accuracy - Combine with regular code reviews - Set up as a pre-release checklist item @@ -197,13 +204,13 @@ The sync command thoroughly checks: 1. **Initial Setup:** Use `/docs:generate-docs` to create documentation structure 2. **Continuous Sync:** Use `/docs:sync-docs` regularly during development -3. **Pre-Release:** Run `/docs:sync-docs 20` before releases to catch all changes +3. **Pre-Release:** Run a wider window (e.g. `/docs:sync-docs 7` or `/docs:sync-docs 50 commits`) before releases to catch all changes 4. **After Merges:** Sync after merging feature branches to update docs ### Performance Optimization -- Use lower commit counts (3-5) for quick daily syncs -- Use higher commit counts (10-20) for comprehensive pre-release checks +- Use a short window (the default `1` day, or `3`) for quick daily syncs +- Use a wider window (e.g. `7` days, or `20-50 commits`) for comprehensive pre-release checks - Run generate-docs once, then rely on sync-docs for updates ### Integration Ideas diff --git a/plugins/docs/.claude-plugin/plugin.json b/plugins/docs/.claude-plugin/plugin.json index 30c7715..424d579 100644 --- a/plugins/docs/.claude-plugin/plugin.json +++ b/plugins/docs/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "docs", - "version": "1.1.1", + "version": "1.2.0", "description": "Generate and keep documentation in sync with your codebase", "homepage": "https://github.com/Flopsstuff/flugins", "author": { diff --git a/plugins/docs/commands/sync-docs.md b/plugins/docs/commands/sync-docs.md index f99510d..2c7ae70 100644 --- a/plugins/docs/commands/sync-docs.md +++ b/plugins/docs/commands/sync-docs.md @@ -6,34 +6,45 @@ disable-model-invocation: false # Sync Documentation with Recent Changes -Usage: `/docs:sync-docs [number_of_commits]` +Usage: `/docs:sync-docs [days | N commits]` -Analyze recent {number_of_commits} and update documentation to match current codebase: +Analyze recent changes and update documentation to match current codebase: -1. Extract the {number_of_commits} from the command arguments: - - If a {number_of_commits} is provided, use that value (e.g., `/docs:sync-docs 10` → analyze 10 commits) - - If no {number_of_commits} is provided, use 5 as default (e.g., `/docs:sync-docs` → analyze 5 commits) +1. Parse `$ARGUMENTS` to determine the lookback window. The window is measured in **days by default**: + - **No argument** (e.g., `/docs:sync-docs`) → **days mode**, default **1 day** (look back 1 day). + - **A bare number** (e.g., `/docs:sync-docs 3`) → **days mode**, look back that many days (3 days). + - **A number followed by the `commits` keyword** (e.g., `/docs:sync-docs 10 commits`) → **commits mode**, analyze exactly that many commits (10 commits). Commits mode is selected ONLY when the explicit `commits` (or `commit`) keyword follows the number. + - Examples: + - `/docs:sync-docs` → last 1 day (days mode) + - `/docs:sync-docs 7` → last 7 days (days mode) + - `/docs:sync-docs 10 commits` → last 10 commits (commits mode) + - `/docs:sync-docs 1 commit` → last 1 commit (commits mode) -2. Analyze recent commits to understand changes: - - Use `git log -N -p` to get full commit history with diffs (where N is the number of commits) - - Review commit messages and full diff to understand the context of changes - - Use `git log -N --name-only` to list all files changed in these commits - - **IMPORTANT**: Read the CURRENT state of all changed files from the repository to understand the actual implementation +2. Build the git commands based on the parsed window: + - **Days mode** (N days): use `git log --since="N days ago" -p` to get full diffs and `git log --since="N days ago" --name-only` to list changed files. + - **Commits mode** (N commits): use `git log -N -p` to get full diffs and `git log -N --name-only` to list changed files. -3. Read all modified files from recent commits: - - For each file changed in the analyzed commits, read its CURRENT content +3. Analyze the commits in the window to understand changes: + - Run the `-p` command from step 2 to get full commit history with diffs. + - Review commit messages and full diffs to understand the context of changes. + - Run the `--name-only` command from step 2 to list all files changed in the window. + - **Empty-window guard**: If the git log returns no commits (e.g., an empty time window in days mode, or an invalid/zero window), stop here. Report `"no commits in the last N days, nothing to sync"` (substituting the resolved window) and do nothing destructive — make no documentation edits. + - **IMPORTANT**: Read the CURRENT state of all changed files from the repository to understand the actual implementation. + +4. Read all modified files from the analyzed commits: + - For each file changed in the window, read its CURRENT content - Pay special attention to: - New files added (understand their purpose and functionality) - Modified files (understand what changed and why) - Deleted files (ensure they're not referenced in docs) - Analyze code to understand features, APIs, configuration, and architecture -4. Find and scan the documentation folder: +5. Find and scan the documentation folder: - Search for common documentation folder names in the project root: `docs/`, `doc/`, `documentation/` - Check for documentation indicators in README.md or project config files - Once the documentation folder is identified, scan it to identify all documentation files -5. Compare the documentation content with actual codebase state: +6. Compare the documentation content with actual codebase state: - Match documentation against CURRENT file contents (not just diffs) - Understand the full context of changes by reading actual code - Identify inconsistencies between docs and code: @@ -44,13 +55,13 @@ Analyze recent {number_of_commits} and update documentation to match current cod - Broken links to non-existent files - Configuration changes not reflected -6. Update all affected documentation files to match current state: +7. Update all affected documentation files to match current state: - Base updates on ACTUAL current file contents - Ensure code examples reflect real implementation - Update API signatures, parameters, and return values - Fix broken references and links -7. Maintain documentation structure: +8. Maintain documentation structure: - **Root index.md**: Ensure there's an `index.md` in the docs root folder - Contains links to ALL files and folders at that level - Each link has a short description of content @@ -64,7 +75,7 @@ Analyze recent {number_of_commits} and update documentation to match current cod - Keep structure flat when possible for better navigation - **Update index files**: When adding/modifying docs, always update relevant `index.md` files -8. Provide short summary of all changes made +9. Provide short summary of all changes made Be thorough and check: