Repository navigation
docs(#6030): add doc-update guidance for new CLI command additions - #6031
fullsend-ai-coder[bot] wants to merge 2 commits into
Conversation
AGENTS.md already instructs agents to grep docs when removing or renaming CLI commands, but had no symmetric rule for additions. This caused the code agent on PR #6022 to miss 5 documentation files that enumerate mint subcommands when adding `mint delete`. Add a new bullet alongside the existing removal/rename guidance that tells agents to grep `docs/` for sibling subcommands when adding a new CLI subcommand or public API endpoint and update every file that enumerates the parent command's subcommands. Closes #6030
|
🤖 Finished Review · ✅ Success · Started 10:44 AM UTC · Completed 10:55 AM UTC Commit: |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
ReviewFindingsMedium
Low
Previous runReviewFindingsMedium
Low
Labels: PR modifies AGENTS.md (meta-docs/conventions), which follows the repo convention of the documentation label without component/docs. |
|
/fs-fix |
|
🤖 Finished Fix · ✅ Success · Started 8:30 AM UTC · Completed 8:35 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.18 |
Replace 'command-tree docs' with 'docs/guides/dev/cli-internals.md' in the new CLI subcommand guidance bullet for naming consistency with other path-based references in the same section. Addresses review feedback on #6031
🔧 Fix agent — iteration 1 (human-triggered)Addressed 1 of 2 review findings. Fixed naming-consistency by replacing informal 'command-tree docs' with the concrete path 'docs/guides/dev/cli-internals.md'. The protected-path finding is informational (human approval required) and does not require a code change. Fixed (1):
Disagreed (1):
Tests: passedNext steps:
|
|
🤖 Finished Review · ✅ Success · Started 8:36 AM UTC · Completed 8:52 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $3.71 |
|
/fs-fix rebase and solve conflicts |
|
🤖 Finished Fix · ❌ Failure (post-script /home/runner/work/fullsend/fullsend/.fullsend/.fullsend-cache/resources/sha256/1704f826be06352c5aa727ca7a68e6bc3db1837e9743e1727323664169eefe2b/scripts/post-fix.sh failed: exit status 1) · Started 8:40 AM UTC · Completed 8:46 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.53 |
|
The fix agent completed, but the post-fix script failed before finishing. Workflow run: https://github.com/fullsend-ai/fullsend/actions/runs/32948816895 Details: |
|
Risk Assessment: moderate (2/5) DetailsTiny additive-only documentation change (1 file, 1 line) by a bot author to a protected path (AGENTS.md). Low metadata risk elevated slightly by high file churn history. |
| - Never commit secrets (tokens, API keys, PEM keys, gcloud credentials) or sensitive data (GCP project names, service account identifiers, Model Armor template names, internal hostnames). Use environment variables with no defaults for sensitive values. | ||
| - When adding a new doc under `docs/`, check `docs/.vitepress/config.ts` sidebar config. Sections using `getMarkdownFiles()` are auto-discovered. All other sections need a manual `{ text, link }` entry. Also add the new folder's prefix to `search.options.scopes` in the same file so the folder's pages are reachable when search scope pills are active. | ||
| - When removing or renaming a CLI command, public API, or user-facing feature, grep all documentation files under `docs/` for references to the old name and update or remove them. Pay special attention to `docs/cli/`, `docs/guides/`, and any getting-started or operations guides that walk through the removed workflow. | ||
| - When adding a new CLI subcommand or public API endpoint, grep `docs/` for references to sibling subcommands or endpoints (e.g., when adding `mint delete`, search for `mint deploy`) and add documentation to every file that enumerates the parent command's subcommands or the API's endpoints. Pay special attention to `docs/cli/`, `docs/guides/dev/cli-internals.md`, operations guides, and infrastructure references. |
There was a problem hiding this comment.
[medium] stale branch / merge conflict
The PR was branched from an older commit. The removal/rename rule on current main has since been updated to include or changing the behavior or output format and additional bullet points have been added between this rule and the Topic-specific guidance heading. The diff context no longer matches main, so a merge conflict is certain. During conflict resolution, the new addition line could be lost or misplaced.
Suggested fix: Rebase the PR branch onto current main before merging. Place the new addition line after the updated removal/rename rule.
| - Never commit secrets (tokens, API keys, PEM keys, gcloud credentials) or sensitive data (GCP project names, service account identifiers, Model Armor template names, internal hostnames). Use environment variables with no defaults for sensitive values. | ||
| - When adding a new doc under `docs/`, check `docs/.vitepress/config.ts` sidebar config. Sections using `getMarkdownFiles()` are auto-discovered. All other sections need a manual `{ text, link }` entry. Also add the new folder's prefix to `search.options.scopes` in the same file so the folder's pages are reachable when search scope pills are active. | ||
| - When removing or renaming a CLI command, public API, or user-facing feature, grep all documentation files under `docs/` for references to the old name and update or remove them. Pay special attention to `docs/cli/`, `docs/guides/`, and any getting-started or operations guides that walk through the removed workflow. | ||
| - When adding a new CLI subcommand or public API endpoint, grep `docs/` for references to sibling subcommands or endpoints (e.g., when adding `mint delete`, search for `mint deploy`) and add documentation to every file that enumerates the parent command's subcommands or the API's endpoints. Pay special attention to `docs/cli/`, `docs/guides/dev/cli-internals.md`, operations guides, and infrastructure references. |
There was a problem hiding this comment.
[low] architectural-coherence
The new addition-guidance bullet references docs/guides/dev/cli-internals.md as a specific callout that is absent from the sibling removal/rename rule. This asymmetry is minor but worth noting for future alignment.
Suggested fix: Consider whether docs/guides/dev/cli-internals.md should also be mentioned in the removal/rename rule for symmetry.
|
Closing, complications. |
|
🤖 Finished Retro · ✅ Success · Started 8:57 AM UTC · Completed 9:11 AM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.95 |
Retro Analysis: PR #6031Outcome: Closed without merging after 16 days idle and two fix iterations. A 1-line documentation change to AGENTS.md was abandoned due to cascading complications from branch staleness and a known post-script bug. Timeline
Evidence for existing issues
Workflow quality assessment
Notes
Proposals skipped (target repo not allowed)File manually or update
|
Summary
Add symmetric doc-update guidance for CLI command additions to AGENTS.md. The existing rule covers removals and renames but not additions, which caused the code agent on PR #6022 to miss 5 documentation files when adding
mint delete.Changes
docs/for sibling subcommand references when adding a new CLI subcommand or public API endpoint, and update every file that enumerates the parent command's subcommandsTesting
grep -q 'adding a new CLI subcommand')gitlint --commit HEADpassesNote:
pre-commitcould not run (sandbox network policy blocksgit fetch). Manual pre-commit verification is required.Closes #6030
Post-script verification
agent/6030-agents-md-doc-guidance)743f99d88b883f61b19f09d00b723f7a3f8ae4f8..HEAD)