skills.rest
cockroachdb
cockroachdbOFFICIAL
Explore all skills by this author →
WebsiteGitHub

doc-catcher

Audit Go package comments for contradictions with actual code behavior.

6.0k|578|Updated Jul 17, 2018
Search Tags:#static analysis#documentation audit#godoc#GO#pebble#Code review#Code comments
One-click install
npx skills add https://github.com/cockroachdb/pebble --skill doc-catcher
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: doc-catcher
Source: https://github.com/cockroachdb/pebble/tree/main/.claude/skills/doc-catcher
Command: npx skills add https://github.com/cockroachdb/pebble --skill doc-catcher

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Code comments in Go packages drift out of sync with the code over time, and misleading documentation causes engineers to write incorrect calling code, debug in the wrong direction, or violate invariants. This Skill finds confirmed comment/code mismatches so documentation can be trusted again.

Core Features & Use Cases

  • Two-stage audit workflow: First builds a package understanding artifact, then audits comments against the actual code contract using dedicated subagents.
  • Severity-ranked report: Produces a conservative, evidence-backed report ordered by severity (high/medium/low), with file:line citations and quoted comments.
  • Pebble/CRDB-aware focus: Prioritizes load-bearing comment areas such as iterator semantics, ownership of returned slices, sequence-number visibility, tombstone rules, and locking preconditions.
  • Use Case: Point it at a Pebble package like the iterator or sstable package to surface stale godoc claims about SeekGE semantics or zero-value validity before they mislead a new contributor.

Quick Start

Run the doc-catcher skill on the Go package at internal/manifest to audit its comments for contradictions with the code.

Frequently Asked Questions about doc-catcher

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit Go code comments for correctness?▼

Run this skill with a repo-relative path to a Go package directory. It builds an understanding of the package's actual contract, then audits every comment claim against the code and returns a severity-ranked report of confirmed mismatches.

What kinds of comment defects does this audit find?▼

It finds comments making specific falsifiable claims about behavior, contracts, invariants, return values, ordering, ownership, or preconditions that the code contradicts. It deliberately excludes typos, missing docs, TODOs, and stylistic disagreements.

Does the audit suggest fixes for incorrect comments?▼

No, the report contains only confirmed comment/code mismatches ordered by severity with no patch suggestions. It is a triaged doc-fix list intended for a senior engineer to act on.

Can this skill detect actual code bugs instead of doc bugs?▼

No, it assumes the code is correct and the comment is the defect whenever they disagree. Code-level bug hunting is explicitly deferred to the separate bug-catcher skill.

Why does the audit focus on iterator and ownership comments in Pebble?▼

Comments about iterator positioning, slice ownership, sequence-number visibility, and tombstone rules are load-bearing contracts that callers rely on. When these drift from the code, they cause incorrect calling code and violated invariants.

Related Skills

Explore More Software Engineering Skills→
xiaolaixiaolai
6

lang-go

Detect exported identifiers in Go code and enforce godoc-compliant comments for public APIs.

Community
Intermediate
przbaduprzbadu
1

pr-review-fixer

Extract and validate GitHub pull request review comments before applying code fixes.

Community
Advanced
vertexcover-iovertexcover-io
4

doc-quality-guard

Audit repository documentation for code accuracy and tone, then generate a fix spec.

Official
Advanced
AissenLiuAissenLiu

requesting-code-review

Automates pre-commit verification with security scans, quality gates, and an auto-fix loop.

Community
Advanced