chore(skills): review README and repo about text on every release#1429
Conversation
Add a "Repo about text" check to Step 5 of the /release skill so the GitHub description and topics are reviewed each release, not just when user-facing features change. Update the PR body template to include the new checklist items.
|
Claude finished @carlos-alm's task —— View job PR Review: chore(skills): review README and repo about text on every release
Root Cause AnalysisProblem Being Solved: The GitHub repository "about" metadata (description, topics, homepage URL) was not part of the release checklist, so it could silently drift out of sync as the project evolved. This PR adds an explicit review step and direct API commands so the agent performing the release doesn't forget or skip it. Why This Approach: Adding it to the existing Step 5 (alongside README review) is logical — both are non-committed, human-visible documentation surfaces. The Risk Assessment: Low. This is a pure documentation/skills change that affects only the Claude Code release skill. No source code, no tests, no configuration touched. Phase 2: Configuration Change DetectionNo linting rules, TypeScript flags, test timeouts, or build configuration were touched. ✓ Phase 3: Test IntegrityNo test files modified. ✓ Phase 4: Code Quality — Minor Issues1. Internal contradiction on recording "about" changes (lines 210 vs 235) Line 210 says:
But line 235 (Step 7 PR creation instruction) says:
And the PR body template in Step 7 adds:
These are contradictory. Line 210 explicitly says no PR entry needed, but Step 7 tells the agent to record what was updated in the PR description. The intent is clearly to record it (good!), but the wording at line 210 should be corrected to say something like: "these changes don't require a commit, but record any changes made in the PR description." 2. gh api --method PUT repos/optave/ops-codegraph-tool/topics \
-f "names[]=cli" -f "names[]=code-analysis" -f "names[]=dependency-graph" -f "names[]=tree-sitter"The skill already explains "replaces the full list — include all desired topics," which is the key risk here: a naive agent might copy this template verbatim and wipe topics not in this example (e.g., 3. Minor wording: "no PR entry" vs "record in PR description" (line 210) The note says Phase 5: Backlog Compliance
Final Assessment |
Greptile SummaryThis PR extends the
Confidence Score: 5/5Safe to merge — the change is purely additive instructions in a skill document with no runtime code paths. The diff touches only a Markdown skill document. The new 'about' sub-step follows a clean fetch-review-update pattern, the atomic-replace warning for the topics PUT is explicit, and the PR body template now has a structured placeholder for recording metadata changes. No gaps or conflicting instructions were found. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Step 5: Update README.md\nand repo about text] --> B[README.md sub-step]
A --> C[Repo about text sub-step]
B --> B1[Check commands/MCP tables]
B --> B2[Check roadmap section]
B --> B3[Roadmap ordering cross-check\nvs ROADMAP.md]
C --> C1["gh api GET\nfetch description, homepage, topics"]
C1 --> C2{Any field stale?}
C2 -->|description / homepage| C3["gh api PATCH\n-f description=... -f homepage=..."]
C2 -->|topics| C4["gh api PUT /topics\nstart from fetched list,\nadd/remove as needed"]
C2 -->|nothing stale| C5[No API call needed]
C3 --> C6[Record changes\nin PR description]
C4 --> C6
C5 --> C6
B3 --> D[Step 7: Create PR]
C6 --> D
D --> D1["PR body includes:\n- Repo about updated: placeholder\n- README roadmap order matches ROADMAP.md\n- Repo about description and topics are current"]
Reviews (5): Last reviewed commit: "Merge branch 'main' into chore/release-s..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ```bash | ||
| # Update description and/or homepage | ||
| gh api --method PATCH repos/optave/ops-codegraph-tool \ | ||
| -f description="NEW DESCRIPTION" \ | ||
| -f homepage="https://..." | ||
|
|
||
| # Update topics (replaces the full list — include all desired topics) | ||
| gh api --method PUT repos/optave/ops-codegraph-tool/topics \ | ||
| -f "names[]=cli" -f "names[]=code-analysis" -f "names[]=dependency-graph" -f "names[]=tree-sitter" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
PUT /repos/{owner}/{repo}/topics replaces the complete topics list atomically. The inline note says "replaces the full list — include all desired topics," but the example command only enumerates four topics. An agent that uses the example as a near-literal template (rather than building the list from the fetched topics in the earlier gh api call) would silently drop any topics not in that hardcoded example. Prefacing the command with an explicit instruction to start from the fetched list — e.g., "Merge the fetched topics with any additions/removals before running the PUT; do not rely on the example list below" — would prevent accidental topic loss.
There was a problem hiding this comment.
Fixed — added two comment lines before the PUT example making the full-replace semantics explicit: 'start from the fetched list above, then add/remove as needed' and 'This PUT replaces ALL topics atomically; do NOT copy the example below verbatim — build the full list from the currently active topics first, then adjust.'
…ut-changes placeholder (#1429)
|
Addressed Claude's review feedback:
|
|
Claude finished @carlos-alm's task —— View job Re-review: chore(skills): review README and repo about text on every release
All three issues from the original review are correctly resolved: Issue 1 — Line 210 contradiction ✓ Issue 2 — PUT /topics full-replace semantics ✓ This directly addresses the risk of an agent silently wiping unlisted topics by copying the example verbatim. Issue 3 — PR template placeholder for "about" changes ✓ Agents have a designated, structured place to document exactly what changed (or confirm nothing changed). Final AssessmentAll feedback addressed. The skill is now internally consistent — Step 5's note, Step 7's PR creation instruction, and the PR body template all agree on the expected behavior. The full-replace warning for Rating: ✓ Ready to merge |
1 participant
Summary
/releaseskill, so the GitHub repository description, homepage URL, and topics are reviewed on every release (not just when user-facing features change)What changed
Step 5 is renamed from Update README.md to Update README.md and repo "about" text and now includes:
gh api repos/optave/ops-codegraph-tool --jq ...gh api --method PATCHandPUT /topicscommands to apply updates directly (no commit needed)Step 7 PR body template gains:
- [ ] README roadmap order matches ROADMAP.md- [ ] Repo "about" description and topics are currentTest plan
/releaseskill runs Step 5 with both README and "about" checks