chore: add review-docs and generate-docs Claude Code skills - #171
Open
shimoncohen wants to merge 5 commits into
Open
shimoncohen wants to merge 5 commits into
shimoncohen wants to merge 5 commits into
Conversation
Runs documented flows/examples against a live environment and reports doc / deployment / env findings. Helper script handles doc parsing, env checks, port-forwards and safe request execution; env configs live in ~/.claude/review-envs since they hold internal hostnames. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Generator documents a deployment change from declared intent verified live; mismatches are reported as deployment findings instead of being documented. Discovery is protocol-agnostic: docrev gains shape/shape-diff (structural XML/JSON comparison), deploy-diff, inventory (helm-release aware) and pod-read (secrets masked). Per-service knowledge accumulates as recipes. Helper moves to .claude/tools/docrev, shared by both skills. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
shimoncohen
changed the title
Adds docrev pod-call (query a backend from inside its pod) and fixes a false "unfilled placeholder" on XML elements in request bodies. The skill now requires localising mismatches hop by hop and verifying a cause before posting it; the pycsw recipe records the gotchas found. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Found by running review-docs against raster, 3d, vector and dem envs. - extract: curl-labelled blocks, multi-line KVP URLs, lowercase/hyphenated placeholders, styled <details>, labelled POST blocks, bodies whose endpoint is in the prose, long and one-line fences, "``` bash" - call: token as header and/or param, env-wide headers, read_posts, read_only envs, host allowlist so tokens never reach third-party hosts, ca_file, --no-auth, --no-forward, --base, OLD=>NEW subs, response headers, tokens redacted from saved bodies - summarize: images/archives, GeoJSON, capabilities identifiers, OpenAPI paths, WCS 1.0 ServiceException Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- extract: xml near "request" prose is a body only when its root is an OGC operation; short "Response:" labels mark example responses - pod-call: blame python3 only when it is actually missing; report in-pod connection errors instead of a traceback Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds two Claude Code skills sharing one helper.
/review-docs: runs a docs PR's documented flow (or standalone examples) against a live environment and reports doc / deployment / env / unverified findings; draft PR comments are posted only after approval./generate-docs: documents a deployment change (e.g. a helm PR). Discovers what changed and how each service describes itself, documents the declared intent verified live, reports intent-vs-live mismatches as deployment findings, stops for plan approval, then writes pages from sibling templates, self-reviews with/review-docs, and opens a draft PR. Protocol-agnostic; per-service knowledge accumulates ingenerate-docs/recipes/(seeded with CSW/pycsw, WCS/GeoServer, S3 download gateway)..claude/tools/docrev/docrev.py(+test_docrev.py,python3 -m unittest test_docrev):extract: doc → steps/tabs/requests with line numbersenv discover|check|forward|stop,inventory: route admission, endpoints, Helm-release-aware inventory, port-forwards with retrycall: one request; writes refused unless allowed, token redacted, compact summaryshape/shape-diff: structural XML/JSON comparison (doc example vs live, declared vs served)deploy-diff: deployment PR → new files and added image/route/dependency keyspod-read: read config/code inside a running pod, secrets maskedEnv configs are read from
~/.claude/review-envs/<env>.yaml, not the repo (internal hostnames; repo is public). Run output goes to gitignored.claude/review-runs/.Validated against #163 / helm-charts#684 on dem-dev: reproduces the manual review findings (Polygon GML2 filter rejected, v2 catalog serving v1-shaped records via
shape-diff, unadmitted v2 routes).🤖 Generated with Claude Code