Menu
Review dashboard PRs needing your response and generate high-confidence update proposals for PRs where maintainers are waiting
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Introduce codespell spell-checking to a project. Creates branch, config file, CI workflow (GitHub Actions or Forgejo Actions for Codeberg), pre-commit hook. Lists typos, helps identify paths/words to ignore, and fixes typos interactively. Use when setting up codespell in a new project.
Introduce REUSE specification compliance (LICENSES/ directory, REUSE.toml, SPDX headers) to a software project or BIDS dataset, then validate it. Covers BIDS data-vs-code separation, DUO (Data Use Ontology) integration, DEP-3 patch tagging for vendoring repos, and integration with tox / pre-commit / Makefile / GitHub Actions. Use when adding licensing metadata to a project, fixing `reuse lint` failures, licensing a BIDS dataset, or annotating patches in a vendoring repo.
Introduce git-bug distributed issue tracking to a git project. Configures GitHub bridge, syncs issues, pushes refs, and documents workflow in DEVELOPMENT.md and CLAUDE.md. Use when setting up git-bug in a new project.
Annotate a paper or work with CRediT (Contributor Roles Taxonomy) author contributions and render the LaTeX byline. Creates a `.tributors.credit.yaml` overlay (single source of truth, compatible with con/tributors), seeds it from sibling repos' git history when present, renders the "Author Contributions" section into LaTeX or Markdown for the target venue, emits JATS XML for publisher metadata, and (via render_authors.py) renders the `\author{}` block with affiliation references. Use when a paper needs a CRediT statement, when standardising contributor attribution across a multi-repo work, when authors need an auto-generated byline + affiliation block, or when the user mentions CRediT / NISO Z39.104 / contributor roles / author contribution section.
Load a PR's review feedback (human + bot) **and CI status**, classify each comment, and recommend what to address vs dismiss with draft responses. CI failures (merge conflicts, lint, tests, workflow runs) are first-class — diagnose, propose a fix, and bundle into the same actionable report. Works from a local repo directory or a PR URL.
Check the health and maintenance status of a GitHub project. Use when user asks about project status, whether a project is maintained, abandoned, or looking for alternatives. Analyzes commit history, releases, issues, PRs, and searches for active forks or community discussions about project future.
| name | pr-review-update |
| description | Review dashboard PRs needing your response and generate high-confidence update proposals for PRs where maintainers are waiting |
Review PRs from the improveit-dashboard where upstream authors have requested changes (listed in "Needs Your Response"), analyze the feedback to determine if updates can be made with high confidence (≥90%), and generate clear actionable instructions for review and submission.
For codespell PRs requiring rebase, the skill will automatically attempt the rebase and clean up history to maintain a tight, clean commit structure.
This skill uses the following values. Adjust for your setup by editing this section:
~/proj/improveit-dashboard — path to improveit-dashboard checkout~/proj/misc — path where PR repos are clonedyarikoptic — your GitHub usernamegh-yarikoptic — git remote name for your forkThroughout this document, these names refer to the configured values above.
The user may provide optional arguments:
--repo <pattern>: Filter by repository name (e.g., --repo duckdb)--pr <number>: Analyze specific PR number--min-confidence <0-100>: Override default 90% confidence threshold (default: 90)--limit <N>: Limit to top N PRs by waiting time (default: 10)--show-all: Show all awaiting PRs, not just top N--auto-rebase: Automatically perform rebase for high-confidence PRs (default: true for codespell PRs)$DASHBOARD_DIR/data/repositories.json$DASHBOARD_DIR/READMEs/$GITHUB_USER.md$REPOS_DIR/ with PR branch checked outgh) authenticated for fetching additional PR details if neededRead the pre-collected PR data from $DASHBOARD_DIR/data/repositories.json.
Filter for PRs where:
author == "$GITHUB_USER"response_status == "awaiting_submitter" (maintainer has responded, waiting for you)status == "open" (not merged or closed)Apply any user-provided filters from arguments.
Sort filtered PRs by:
days_awaiting_submitterExtract key metadata for each PR:
readthedocs/readthedocs.org)ci_status fieldhas_conflicts fielddays_awaiting_submittertool field (codespell, shellcheck, other)For each prioritized PR, examine last_developer_comment_body to categorize the request:
Actionable Categories:
Merge Conflicts (has_conflicts: true)
git fetch upstream && git rebase upstream/mainCI Failures (ci_status: "failing")
Code Review Feedback
Questions/Clarifications
Approval Pending Action (e.g., "looks good", "yes, please")
Non-Actionable (Skip or Manual Review):
For each actionable PR, check if repo exists locally:
ls -d $REPOS_DIR/<repo-name>/.git 2>/dev/null
Extract repo name from repository field (e.g., readthedocs/readthedocs.org → readthedocs.org).
If repo exists:
git -C $REPOS_DIR/<repo-name> branch --show-currentenh-codespell)git -C $REPOS_DIR/<repo-name> status --porcelainIf repo missing:
https://github.com/$GITHUB_USER/<repo-name>Assign confidence score (0-100%) based on feedback analysis:
100% Confidence:
90-95% Confidence:
develop instead of main)80-89% Confidence:
<80% Confidence (Manual Review):
Exclude from proposals (<90% unless --min-confidence lowered):
For codespell PRs (tool == "codespell") that need rebasing, perform the following automated workflow to maintain clean history:
Goal: End with a clean codespell state, no conflicts, and tight commit history.
Before rebasing, identify commits in the PR branch:
cd $REPOS_DIR/<repo-name>
git log --oneline origin/<base-branch>..HEAD
Look for:
.codespellrc or similar config.github/workflows/ filesCreate a backup tag before any operations:
git tag backup-before-rebase-$(date +%Y%m%d-%H%M%S)
This allows recovery via git reflog and git reset --hard backup-before-rebase-<timestamp> if needed.
Attempt 1: Direct rebase
git fetch origin
git rebase origin/<base-branch>
If rebase succeeds cleanly:
If rebase has conflicts:
Follow this conflict resolution strategy prioritizing clean history:
Abort current rebase
git rebase --abort
Drop automated typo fix commit first
# Interactive rebase to drop the automated fix commit
git rebase -i origin/<base-branch>
# In the editor, change 'pick' to 'drop' for the automated typo fix commit
# Keep config and workflow commits
Retry rebase
git rebase origin/<base-branch>
If still conflicts:
git rebase --abortIf rebase succeeds after dropping commits:
After successful rebase, check if the workflow file includes the redundant codespell-problem-matcher@v1 step and remove it if present.
Background: The actions-codespell@v2 action internally includes the problem matcher functionality, so the explicit codespell-project/codespell-problem-matcher@v1 step is redundant.
Process:
Check if workflow file has the problem-matcher step:
cd $REPOS_DIR/<repo-name>
# Look for the workflow file (usually .github/workflows/codespell.yml)
workflow_file=$(find .github/workflows -name "*codespell*" -o -name "*spell*" | head -1)
if [ -n "$workflow_file" ]; then
if grep -q "codespell-project/codespell-problem-matcher" "$workflow_file"; then
echo "Found redundant problem-matcher step in $workflow_file"
else
echo "No problem-matcher step found, skipping cleanup"
fi
fi
Remove the problem-matcher step if found:
Use Edit tool to remove the entire step block:
BEFORE:
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Annotate locations with typos
uses: codespell-project/codespell-problem-matcher@v1
- name: Codespell
uses: codespell-project/actions-codespell@v2
AFTER:
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Codespell
uses: codespell-project/actions-codespell@v2
Amend the workflow commit:
Find the commit that added the workflow file and amend it:
# Find the commit that added or last modified the workflow
workflow_commit=$(git log --oneline --diff-filter=A -- "$workflow_file" | head -1 | awk '{print $1}')
# If workflow was added in this PR branch (not in base branch):
if git log --oneline origin/<base-branch>..HEAD | grep -q "$workflow_commit"; then
# Amend the workflow commit
# First, stage the cleaned workflow file
git add "$workflow_file"
# Interactive rebase to edit the workflow commit
git rebase -i origin/<base-branch>
# In the editor, change 'pick' to 'edit' for the workflow commit
# After rebase stops:
git commit --amend --no-edit
git rebase --continue
else
# Workflow already existed in base branch, just commit the cleanup
git add "$workflow_file"
git commit -m "Remove redundant codespell-problem-matcher step
The actions-codespell@v2 action internally includes the problem matcher, so the explicit codespell-project/codespell-problem-matcher@v1 step is redundant.
Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com" fi
4. **Alternative: If workflow commit is first commit in PR:**
Simpler approach when workflow was added in this PR:
```bash
# Stage the cleaned workflow file
git add .github/workflows/codespell.yml
# Amend the first commit (assuming it's the workflow commit)
# Use git rebase -i to identify which commit added the workflow
git log --oneline --reverse origin/<base-branch>..HEAD
# If it's the first commit after base:
git rebase -i origin/<base-branch>
# Mark the workflow commit as 'edit', then:
git commit --amend --no-edit
git rebase --continue
After successful rebase, check for typos and apply fixes BEFORE reporting to user:
Step 1: Check what ambiguous typos were already fixed in original branch
Before rebase, the original branch may have already fixed ambiguous typos. Check the original typo fix commit:
cd $REPOS_DIR/<repo-name>
# Find the original automated typo fix commit (usually has "DATALAD RUNCMD" or "codespell" in message)
git log backup-before-rebase-<timestamp> --oneline --grep="codespell" --grep="DATALAD RUNCMD" | head -5
# Extract what ambiguous typos were fixed manually before the automated commit
# Look for commits that fixed specific typos before the bulk automated fix
git show <original-typo-fix-commit-hash> | grep -E "^[-+]" | grep -v "^[-+][-+][-+]" | head -100
Identify ambiguous typo fixes from original commit:
trough → through)Step 2: Run codespell to identify all typos:
cd $REPOS_DIR/<repo-name>
uvx codespell . 2>&1 | tee codespell-output.txt
Analyze output:
==> and single suggestion (codespell -w will fix these)==> and multiple suggestions (need manual/AI review)grep -c "^.*:" codespell-output.txtStep 3: Extract ambiguous typos for AI review:
# Get ambiguous typos (multiple suggestions)
grep "," codespell-output.txt > ambiguous-typos.txt
# Get non-ambiguous typos (single suggestion)
grep -v "," codespell-output.txt | grep "==>" > simple-typos.txt
CRITICAL: Fix ambiguous typos BEFORE running codespell -w for non-ambiguous ones.
For each ambiguous typo from ambiguous-typos.txt:
Read the file and context around the typo (5-10 lines):
# Example: ./path/file.cpp:123: trough ==> through, trough
Analyze context to determine correct fix:
Common ambiguous patterns and how to resolve:
trough ==> through, trough
manger ==> manager, manger
loner ==> longer, loner
ot ==> to, of, or, not, it
-ot, a comment like ot her, or code?te ==> the, be, we, to
TE, template<typename TE>)fo ==> of, for, to, do, go
-fo or variable namesDecision logic:
Fix if:
Skip (add to ignore-words-list) if:
Apply fixes using Edit tool:
# For each ambiguous typo determined to need fixing:
# Use Edit tool to change the specific occurrence
Track decisions: Create a list of:
Update .codespellrc with skipped words:
If multiple ambiguous typos are legitimate (not errors), add to config:
# Edit .codespellrc or pyproject.toml
# Add to ignore-words-list: te,ot,fo (if they're template params or flags)
# Add to ignore-regex if it's a pattern (e.g., camelCase identifiers)
Commit ambiguous fixes separately (if substantial):
git add -u
git commit -m "Fix ambiguous typos requiring context review
Fixed based on context analysis:
Skipped (added to ignore-words-list):
Or combine with the datalad run commit if changes are minor.
Apply non-ambiguous typo fixes using datalad run for reproducibility, then REVIEW BEFORE reporting to user:
IMPORTANT: Use datalad run to wrap codespell -w for auditable, reproducible commits.
Note: datalad run works on plain git repositories - no need to initialize as datalad dataset.
CRITICAL POST-FIX REVIEW: After codespell -w runs, review fixes in context to catch false positives.
Check if datalad is available:
datalad --version 2>/dev/null || echo "Need to use uvx"
Apply automated fixes using datalad run:
Option A: If datalad is installed:
cd $REPOS_DIR/<repo-name>
datalad run -m "Fix typos found by codespell
Automated fixes applied by codespell -w after rebase onto main.
Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com" 'codespell -w'
**Option B: If datalad not installed (use uvx):**
```bash
cd $REPOS_DIR/<repo-name>
uvx --from datalad datalad run -m "Fix typos found by codespell
Automated fixes applied by codespell -w after rebase onto main.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>" 'uvx codespell -w'
Option C: Interactive mode (if ambiguous typos remain):
# Prompts for each ambiguous typo with context
datalad run -m "Fix typos interactively with codespell" 'codespell -w -i 3 -C 4'
# Or with uvx:
uvx --from datalad datalad run -m "Fix typos interactively with codespell" 'uvx codespell -w -i 3 -C 4'
The -i 3 flag enables interactive mode, -C 4 shows 4 context lines.
Option D: If using extracted patch (when codespell unavailable):
# Apply patch first, then commit normally (not with datalad run)
git add -u
git commit -m "Fix typos found by codespell
Typo fixes extracted from original commit and re-applied after rebase.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
Why use datalad run?
datalad rerunReview changes after commit:
git show HEAD --stat
git log --oneline -1
Handle ambiguous typos if needed (manual review before datalad run)
codespell -w skipped ambiguous typos, fix them manually firstcodespell -w -i 3After running datalad run with codespell -w, ALWAYS review the changes in context.
Codespell can make incorrect "fixes" that break code or change meaning:
Common False Positive Patterns:
API/Function naming patterns - suffix letters that look like typos:
allocatedp → allocated (WRONG: "p" suffix for pointer variant)deallocatedp → deallocated (WRONG: same pattern)widthIn → within (WRONG: parameter name)readByte → readable (WRONG: method name)Variable naming conventions:
errorOccured → errorOccurred (might be OK, but check usage)hasHappend → hasHappened (might be OK, but check consistency)Test data or intentional misspellings:
Review Process:
Check the diff of the datalad run commit:
git show HEAD --stat
git show HEAD -- path/to/changed/file.c
For each changed file, verify:
Search for related patterns:
# If you find "allocatedp" was wrongly "fixed", search for similar patterns:
git grep -i "allocatedp\|deallocatedp\|somethingp"
# Check if the pattern is used elsewhere:
git diff HEAD -- . | grep "^-.*allocatedp"
Revert incorrect fixes and update config:
Option A: Revert specific lines and add to ignore-words-list
# Undo the commit
git reset --soft HEAD~1
# Revert specific bad changes
git checkout HEAD -- path/to/file/with/bad/fix.c
# Or manually fix using Edit tool
# Update .codespellrc
# Add: ignore-words-list = ...,allocatedp,deallocatedp
# Recommit with datalad run
datalad run -m "Fix typos with codespell" 'codespell -w'
Option B: Use inline pragma for specific lines
When a word is only wrong in specific contexts (correct elsewhere), use inline pragma:
// Before:
{NAME("allocatedp"), CTL(thread_allocatedp)},
// After adding pragma:
{NAME("allocatedp"), CTL(thread_allocatedp)}, // codespell:ignore
IMPORTANT: Use // codespell:ignore without specifying the word.
// codespell:ignore// codespell:ignore allocatedp (codespell 2.4.1+ doesn't parse word-specific pragmas)This tells codespell to ignore all words on that line.
Common scenarios requiring revert + config update:
allocatedp, pread, pwriteUpdate .codespellrc after finding false positives:
# Add to ignore-words-list (case-insensitive):
ignore-words-list = ans,inout,allocatedp,deallocatedp
# Or add to skip paths if entire directory is problematic:
skip = .git*,./extension/vendored_lib/*
Recommit after fixing:
git add .codespellrc
git add -u # Stage reverted files
datalad run -m "Fix typos with codespell (excluding false positives)" 'codespell -w'
Signs of False Positives to Watch For:
When in Doubt:
allocated and allocatedp both exist)IMPORTANT: Not all identifier changes are false positives. Some identifiers DO contain typos that should be fixed.
Codespell can change identifiers (function names, variables, struct fields). These require analysis to determine:
Detection: Find identifier changes in the diff
cd $REPOS_DIR/<repo-name>
# Find changes to function/method names (with parentheses)
git show HEAD | grep -E "^[-+].*\b[a-zA-Z_][a-zA-Z0-9_]*\s*\(" | head -30
# Find changes to struct/object field access (. or ->)
git show HEAD | grep -E "^[-+].*(\.|->)[a-z][a-zA-Z0-9_]*" | head -30
# Find changes to variable declarations
git show HEAD | grep -E "^[-+].*\b(auto|const|static|int|bool|string)\s+(&|\*)?\s*[a-z][a-zA-Z0-9_]*\s*(=|;)" | head -30
Analysis Process for Each Identifier Change:
Read the context (at least 10 lines before/after):
git show HEAD -- path/to/file.cpp | grep -B10 -A10 "changed_identifier"
Ask: Is the original spelling actually wrong?
✅ YES, it's a typo → Keep the fix:
IsAvailble → IsAvailable (missing 'a')varaible → variable (transposed letters)funciton → function (typo in name)❌ NO, it's intentional → Revert:
HasTable → hashtable (valid method name, not a typo)larg → large (convention: larg/rarg = left/right argument)pres → press (abbreviation for "present" or "result")allocatedp → allocated (API naming: 'p' suffix for pointer variant)Check if it's part of an interface/API:
# Is this a public method/function?
git grep -n "class.*HasTable\|DUCKDB_API.*HasTable"
# Is this declared in a header file?
git show HEAD -- "*.h" "*.hpp" | grep "HasTable"
# If yes → Reverting is safer unless certain it's a typo
Check for consistent usage across codebase:
# How many times does the old spelling appear?
git grep -c "HasTable" | grep -v ":0$"
# If used >5 times with same spelling → likely intentional, not a typo
# If used only 1-2 times → might be an actual typo worth fixing
Check for paired patterns (strong signal of intentionality):
# Example: larg/rarg pairing
git show HEAD | grep -E "larg|rarg"
# If you see both larg and rarg → this is an intentional pairing pattern
# Changing only larg to "large" breaks the symmetry → revert
Check for name collisions after fix:
# Would the new name conflict with existing identifier?
git grep -n "hashtable" | head -20
# If "hashtable" already exists as a different entity → collision risk
SPECIAL CASE: Intentional typos in tests:
# Check if change is in test files
git show HEAD --stat | grep "test/"
# Read the test context
git show HEAD -- test/api/test_pending_query.cpp | grep -B5 -A5 "changed_word"
Tests may have intentional typos to verify error handling:
If typo is intentional in test:
// BEFORE codespell:
test_error_message("errorOccured"); // Tests error handling
// AFTER codespell (WRONG):
test_error_message("errorOccurred"); // Now test breaks!
// CORRECT FIX: Add inline pragma and revert
test_error_message("errorOccured"); // codespell:ignore
Use inline pragma // codespell:ignore for intentional typos in tests.
Decision Matrix:
| Original | Changed To | Used >5× | Paired Pattern | Part of API | In Test | Decision |
|---|---|---|---|---|---|---|
HasTable | hashtable | Yes | No | Yes (method) | No | REVERT - Valid method name |
larg | large | Yes | Yes (with rarg) | Yes (struct field) | No | REVERT - Intentional pairing |
pres | press | Yes | No | No (local var) | No | REVERT - Valid abbreviation |
errorOccured | errorOccurred | No | No | No | Yes (test string) | REVERT + PRAGMA - Intentional test typo |
IsAvailble | IsAvailable | No | No | Yes (method) | No | KEEP - Actual typo in method |
varaible | variable | No | No | No | No | KEEP - Actual typo in variable |
Action on False Positives (Intentional Identifiers):
# Option A: Revert specific changes using Edit tool
# Read the file, then Edit to restore original identifier
# Option B: Reset and exclude from next run
git reset --soft HEAD~1
# For common abbreviations used throughout codebase (>10 occurrences):
# Add to .codespellrc ignore-words-list
# Example: larg,rarg,pres
echo "ignore-words-list = ans,inout,larg,rarg,pres" >> .codespellrc
# For intentional typos in tests (error testing):
# Revert and add inline pragma on that specific line
# Example in test file:
test_error("errorOccured"); // codespell:ignore
# For unique identifiers (like HasTable method name):
# Just revert in the code, don't add to global ignore list
# (Too specific to warrant global exclusion)
# Re-run datalad run after corrections
git add .codespellrc test/ # If added pragmas
datalad run -m "Fix typos with codespell (reverted false positives)" 'codespell -w'
Action on Actual Identifier Typos:
# If the identifier really contains a typo (like IsAvailble):
# 1. Keep the codespell fix
# 2. Check if it's part of public API - may need deprecation path
# 3. Search for all uses and ensure they're all updated
git grep -n "IsAvailable" | head -50
# 4. Check if tests need updating
git grep -n "IsAvailable" -- "test/*" "tests/*"
Key Principle:
Analyze first, then decide. Don't blindly revert all identifier changes or blindly accept them all. The goal is correctness: fix actual typos (even in identifiers), but preserve intentional naming.
Function parameters often use single-letter prefixes for parallel data structures. This is especially common in:
a[]/b[] arrays with acount/bcount, aidx/bidxaptr/bptr, aval/bval, asize/bsizeCommon Paired Patterns:
[a-z]count / [a-z]count - array counts (a/b/c prefix)[a-z]idx / [a-z]idx - array indices[a-z]ptr / [a-z]ptr - pointers[a-z]val / [a-z]val - values[a-z]size / [a-z]size - sizes[a-z]arg / [a-z]arg - arguments (e.g., larg/rarg)Why This Matters:
Codespell may "fix" one side of a pair but not the other, creating asymmetric naming that breaks the intentional pattern:
// BEFORE (correct pairing):
void MergeLoop(row_t a[], row_t b[], idx_t acount, idx_t bcount) {
idx_t aidx = 0, bidx = 0;
while (aidx < acount && bidx < bcount) {
// merge logic
}
}
// AFTER codespell (WRONG - breaks pairing):
void MergeLoop(row_t a[], row_t b[], idx_t account, idx_t bcount) {
idx_t aidx = 0, bidx = 0;
while (aidx < account && bidx < bcount) { // ASYMMETRIC!
// merge logic
}
}
The asymmetry (account vs bcount) is the key signal of a false positive.
Detection Strategy:
cd $REPOS_DIR/<repo-name>
# Step 1: Check for changes to variables with single-letter prefixes
git show HEAD | grep -E "^[-+].*\b[a-z](count|idx|ptr|val|size|arg)\b" | head -30
# Step 2: If found, check for pairing in the modified file
# Extract the file path from git show output
file_path=$(git show HEAD --name-only | grep "\.cpp\|\.hpp\|\.c\|\.h" | head -1)
# Read the modified section to check for paired variables
git show HEAD -- "$file_path" | grep -E "\b[a-z](count|idx|ptr|val|size|arg)\b" | head -30
# Look for patterns like:
# - acount and bcount
# - aidx and bidx
# - larg and rarg (already covered in Step 6.7b)
Detection: Asymmetric Changes (One Side Changed, Other Unchanged)
This is the most reliable signal of a false positive in paired variables:
# Check if codespell created asymmetric paired variables
git show HEAD | grep -E "^\+.*\b(account|aindex|apointer)" | while read -r line; do
# Extract the changed identifier
changed=$(echo "$line" | grep -oE "\b(account|aindex|apointer|avalue|asize)\b" | head -1)
# Check if there's a corresponding b* variable in the same file
if git show HEAD | grep -qE "\bbcount\b|\bbidx\b|\bbptr\b|\bbval\b|\bbsize\b"; then
echo "⚠️ ASYMMETRIC CHANGE DETECTED: $changed exists with paired b* variable"
echo " This is likely a false positive - check the context"
fi
done
Warning Signs:
a[] and b[] (parallel arrays)acount, aidx alongside bcount, bidxDecision Logic:
| Changed | Paired With | Pattern | Decision |
|---|---|---|---|
acount → account | bcount exists | Parallel arrays | REVERT - Intentional pairing |
aidx → index | bidx exists | Parallel indices | REVERT - Intentional pairing |
aptr → after | bptr exists | Parallel pointers | REVERT - Intentional pairing |
larg → large | rarg exists | Struct fields | REVERT - Intentional pairing (see 6.7b) |
errcount → errorcount | No pair | Single variable | KEEP - Actual typo fix (if appropriate) |
acount → account | No bcount found | Single variable | ANALYZE - May be legitimate fix |
Action on Paired Variable False Positives:
# Option 1: Add to .codespellrc ignore-words-list
# (Best for patterns used throughout codebase)
echo "ignore-words-list = ...,acount" >> .codespellrc
# Option 2: Revert the specific change
# Read the file and use Edit tool to restore the paired naming
# Then re-run codespell
git add .codespellrc
datalad run -m "Fix typos with codespell (excluded paired patterns)" 'codespell -w'
Example False Positive Analysis:
# Found: acount → account in src/storage/table/update_segment.cpp
cd $REPOS_DIR/duckdb
# Check context
git show HEAD -- src/storage/table/update_segment.cpp | grep -B10 -A10 "account"
# Output shows:
# static idx_t MergeLoop(row_t a[], sel_t b[], idx_t account, idx_t bcount, ...) {
# idx_t aidx = 0, bidx = 0;
# while (aidx < account && bidx < bcount) {
# ...
# }
# }
# Analysis:
# ✅ Found paired pattern: account/bcount (should be acount/bcount)
# ✅ Found paired indices: aidx/bidx
# ✅ Parallel arrays: a[] and b[]
# ✅ Asymmetric change: only acount changed, bcount unchanged
#
# Conclusion: FALSE POSITIVE - Revert and add acount to ignore list
Validation After Fix:
After reverting paired variable false positives and adding to ignore list:
# Verify the pattern is now symmetric
git diff HEAD -- src/storage/table/update_segment.cpp | grep -E "acount|bcount"
# Should show both acount and bcount with symmetric naming
# Verify codespell is happy
codespell
# Exit code should be 0
Key Insight:
Asymmetric changes in paired variables are almost always false positives.
If codespell changes
acount→accountbut leavesbcountunchanged, this breaks an intentional naming pattern and should be reverted.
The heuristic: Look for lone changes in paired contexts.
CRITICAL: Codespell can create duplicate test data by "fixing" intentional variations in test strings.
Test files often use intentionally similar strings to test comparison, sorting, or prefix handling:
"hello" vs "hellow" - testing suffix differences"torororororo" vs "torororororp" - testing character-by-character comparisonWhen codespell "fixes" these, it creates duplicate test data that breaks the test.
Detection: Find duplicate string literals created by codespell
cd $REPOS_DIR/<repo-name>
# Check if codespell created any duplicate string literals in test files
git show HEAD --stat | grep "test.*\.\(cpp\|py\|jl\)$" > /tmp/test-files-changed.txt
# For each changed test file, check for duplicate string constants
while read -r line; do
file=$(echo "$line" | awk '{print $1}')
if [ -f "$file" ]; then
echo "=== Checking $file for duplicate strings ==="
# Extract string literals and find duplicates
git show HEAD -- "$file" | grep -E '^\+.*"[^"]{3,}"' | \
sed 's/.*"\([^"]*\)".*/\1/' | sort | uniq -c | \
awk '$1 > 1 {print " DUPLICATE: \"" $2 "\" appears " $1 " times"}'
fi
done < /tmp/test-files-changed.txt
Specific Check for test_art_keys.cpp Pattern:
# Check if a test file has arrays with duplicate values after codespell
git show HEAD -- test/sql/index/test_art_keys.cpp | \
grep -A 20 "keys.push_back.*CreateARTKey" | \
grep '^\+.*".*"' | sed 's/.*"\([^"]*\)".*/\1/' | sort | uniq -c | \
awk '$1 > 1'
# If duplicates found like:
# 2 hello
# This indicates codespell likely changed "hellow" → "hello"
Analysis Process for Test Data:
Check if string appears in both old and new versions:
# Did we have both "hello" and "hellow" before?
git show HEAD^:test/sql/index/test_art_keys.cpp | grep -o '"hello\w*"' | sort | uniq
# If output shows: "hello" and "hellow" → these were distinct test values
# If now both are "hello" → false positive
Look for patterns indicating intentional variation:
"hello" vs "hellow""torororororo" vs "torororororp""abc", "abcd", "abcde"Check test purpose:
# Read test name and comments
git show HEAD:test/sql/index/test_art_keys.cpp | grep -B5 "hellow" | head -20
# If test is about key comparison, sorting, prefix matching → variations are intentional
Action on Test Data False Positives:
# Option A: Revert and add inline pragma
git show HEAD^:test/sql/index/test_art_keys.cpp > /tmp/original.cpp
cp /tmp/original.cpp test/sql/index/test_art_keys.cpp
# Add inline pragma to prevent future codespell changes
# In the test file, add: // codespell:ignore
keys.push_back(ARTKey::CreateARTKey<const char *>(arena_allocator, "hellow")); // codespell:ignore
git add test/sql/index/test_art_keys.cpp
# Option B: Add to .codespellrc if it's a common test pattern
# (Only if the pattern appears in multiple test files)
echo "# hellow: intentional test data variation" >> .codespellrc
echo "ignore-words-list = ...,hellow" >> .codespellrc
Decision Matrix for Test Strings:
| Context | Pattern | Duplicate After Fix? | Decision |
|---|---|---|---|
| Test array with "hello", "hellow" | Suffix variation | Yes - both "hello" now | REVERT + PRAGMA |
| Test array with "torororororo", "torororororp" | Char difference | No - left as is | KEEP |
| Error message string with typo | Prose/message | No duplicates | KEEP (if testing error text) or FIX (if not) |
| Test expecting "SELCT" to fail | SQL syntax error | N/A - has pragma | REVERT + PRAGMA |
Warning Signs of Test Data False Positives:
push_back, append, add with string literalsKey Principle:
Test data variations are often intentional. If codespell creates duplicates in test arrays, it's likely wrong. Always check if the "typo" was actually testing something specific (error handling, comparison, etc.).
Before reporting to user, verify:
No codespell errors
codespell .
echo "Exit code: $?" # Should be 0 or show only acceptable warnings
No merge conflicts
git status # Should show "nothing to commit, working tree clean"
Clean history
git log --oneline origin/<base-branch>..HEAD
Should show: Config → Workflow → Typo fixes (regenerated, if any)
CRITICAL: NEVER push automatically without explicit user confirmation.
After completing rebase and typo fixes:
Report current state:
echo "=== Branch Status ==="
git log --oneline origin/<base-branch>..HEAD
git status
Verify codespell clean state:
codespell . || echo "Codespell check complete"
Provide push command for user to execute:
# DO NOT EXECUTE - provide this command to user:
echo "Ready to push. User should run:"
echo "cd $REPOS_DIR/<repo-name>"
echo "git push --force-with-lease <remote-name> <branch-name>"
For user's fork:
$FORK_REMOTE or origin (check git remote -v)enh-codespell)For PRs meeting confidence threshold (≥90%), generate detailed action plans with this structure:
For each PR:
Title: Confidence: % Repo Location: $REPOS_DIR/ [or NEEDS SETUP if missing] Branch:
<Action 1> ()
# Exact commands to run
<Action 2>
$REPOS_DIR/<repo-name>For PRs where repos don't exist locally, provide a dedicated section:
Before working on these PRs, clone and configure the following repos:
cd $REPOS_DIR
git clone https://github.com/$GITHUB_USER/<repo-name>
cd <repo-name>
git remote add upstream https://github.com/<owner>/<repo-name>
git fetch --all
# Find PR branch
gh pr view <PR-number> --repo <owner/repo-name> --json headRefName
git checkout <branch-name>
For PRs below confidence threshold, provide:
Title: Confidence: % () Issue:
Generate executive summary at the top of output:
Total PRs Awaiting Your Response: Analyzed: (top priority by wait time or as filtered) High-Confidence Updates: (≥90%) Manual Review Required: (<90%) Repository Setup Needed:
CRITICAL: Always generate a status table at the end of the report.
After preparing PRs, generate a comprehensive status table showing:
Table Format:
## 🆕 Newly Prepared PRs (This Batch)
| Repository | PR | Local Path | Push Status | Notes |
|------------|----|-----------| ------------|-------|
| <owner/repo> | [#<num>](<url>) | `<path>` | 🔄 **READY TO PUSH** | <details> |
## 📦 Previously Prepared PRs (If Any)
| Repository | PR | Local Path | Push Status | Notes |
|------------|----|-----------| ------------|-------|
| <owner/repo> | [#<num>](<url>) | `<path>` | ✅ **PUSHED** / 🔄 **READY TO PUSH** | <details> |
## 🚀 Push Commands
```bash
# NEW: <repo-name>
cd <path>
git push --force-with-lease <remote> <branch>
**Push Status Detection:**
For each prepared PR, check push status by comparing local and remote hashes:
```bash
cd $REPOS_DIR/<repo-name>
git fetch <remote> <branch> 2>/dev/null
local_hash=$(git rev-parse <branch> 2>/dev/null)
remote_hash=$(git rev-parse <remote>/<branch> 2>/dev/null)
if [ "$local_hash" = "$remote_hash" ]; then
echo "✅ **PUSHED** - Already synced"
else
echo "🔄 **READY TO PUSH** - Local ahead of remote"
fi
Status Icons:
Remote Name:
$FORK_REMOTEorigingit remote -vExample Output:
## 🆕 Newly Prepared PRs (This Batch)
| Repository | PR | Local Path | Push Status | Notes |
|------------|----|-----------| ------------|-------|
| duckdb/duckdb | [#19817](https://github.com/duckdb/duckdb/pull/19817) | `$REPOS_DIR/duckdb` | 🔄 **READY TO PUSH** | Rebased, fixed typos |
| foo/bar | [#123](https://github.com/foo/bar/pull/123) | `$REPOS_DIR/bar` | 🔄 **READY TO PUSH** | Removed problem-matcher |
## 📦 Previously Prepared PRs (Awaiting Push)
| Repository | PR | Local Path | Push Status | Notes |
|------------|----|-----------| ------------|-------|
| old/repo | [#456](https://github.com/old/repo/pull/456) | `$REPOS_DIR/repo` | ✅ **PUSHED** | Already synced |
## 🚀 Push Commands
```bash
# NEW: duckdb
cd $REPOS_DIR/duckdb
git push --force-with-lease $FORK_REMOTE enh-codespell
# NEW: bar
cd $REPOS_DIR/bar
git push --force-with-lease $FORK_REMOTE enh-codespell
**Benefits of Status Table:**
1. **At-a-glance status** - User immediately sees what's ready vs already pushed
2. **Prevents duplicate pushes** - Clear indication of what's already synced
3. **Copy-paste commands** - Ready-to-use push commands for unpushed PRs
4. **Tracking across sessions** - Shows PRs from previous sessions still awaiting push
5. **Full context** - URLs, paths, and notes in one place
## Operating Principles
### Data-Driven
- **Trust dashboard data**: Use existing `repositories.json` as source of truth
- **Leverage metadata**: CI status, conflicts, waiting days already calculated
- **No redundant API calls**: Only fetch additional data if explicitly needed
- **Respect rate limits**: Minimize GitHub API usage
### Focus on "Needs Your Response"
- **Primary target**: PRs with `response_status == "awaiting_submitter"`
- **Prioritize by wait time**: Address longest-waiting PRs first
- **CI failures first**: Broken CI blocks merge, fix it
- **Conflicts block merge**: Rebase PRs with conflicts
### Conservative Confidence
- **Default ≥90%**: Only propose changes you're highly confident about
- **Transparent scoring**: Explain why confidence is high or low
- **User override**: Allow `--min-confidence` to adjust threshold
- **Manual review escape**: Always provide option for user judgment
### Actionable Output
- **Concrete commands**: Every proposal includes exact bash commands
- **Pre-flight checks**: Verify repo exists, branch is correct, etc.
- **Copy-paste ready**: Commands should work without modification
- **Grouped by action type**: Conflicts, CI, questions, etc.
### Efficiency
- **Top N by default**: Don't overwhelm with all PRs at once (default: 10)
- **Progressive disclosure**: Summary → high-confidence → manual review → setup
- **Batch similar actions**: Group all rebases, all CI fixes, etc.
- **Repo reuse**: If repo is already set up, skip setup steps
## Review Body Formatting (when composing a PR review/comment body)
When this skill is used to write a review body to be posted via
`gh pr review --body-file` or `gh pr comment --body-file` (and not just
internal action notes), apply the **collapsible-details pattern** so the
review doesn't visually overwhelm the PR page:
- Keep a short **TL;DR** section visible by default (~3–6 bullets at the
top — what's broken, what's missing, severity).
- Wrap each subsequent section (design-doc compliance tables, per-issue
detail, suggested tests, line-by-line minor items, recommendations) in
HTML `<details>` blocks. GitHub renders these collapsed by default.
Template:
```markdown
# PR #NNNN — <topic> review
<one-sentence framing of what was reviewed and against what>
## TL;DR
- <key finding 1>
- <key finding 2>
- <verdict / requested actions>
<details>
<summary>1. Design doc requirements vs. implementation</summary>
<the table or detailed body>
</details>
<details>
<summary>2. Specific issues</summary>
### 2.1 <issue title>
<full detail>
### 2.2 ...
</details>
<details>
<summary>3. Recommendations (priority order)</summary>
1. ...
2. ...
</details>
Why: GitHub PR review bodies render full markdown but lack any built-in
collapsing. Long reviews push the conversation timeline down by screens and
discourage maintainers from reading. Collapsible <details> keeps the
summary scannable and signals which sections to drill into.
Reference example: a review applying this pattern is at
https://github.com/dandi/dandi-archive/pull/2799#pullrequestreview-4197495045.
When NOT to use: short reviews (<~30 lines), single-issue comments, or inline review comments on specific lines — collapsing them adds clicks for no benefit.
repositories.json not found, exit with clear errorgh auth login instruction if needed for extra data