feat(ci): add claude-docs-review workflow and GitHub issue solver agent

[sodre]

Summary

• Add claude-docs-review.yml workflow that auto-labels PRs and validates documentation changes against code
• Add github-issue-solver Claude agent for systematic issue resolution
• Update CLAUDE.md with documentation sync workflow instructions

Features

Auto-labeling

PRs are automatically labeled based on changed files:

• code-change - When src/zae_limiter/ files are modified
• documentation - When docs/ files are modified
• needs-docs-review - When public API changes without corresponding docs updates
• infrastructure - When CloudFormation or infrastructure files change
• tests - When test files are modified

Documentation Validation

When docs are changed:

1. Builds documentation in strict mode (mkdocs build --strict)
2. Validates documented imports/exports still exist
3. Comments on PR if build fails

Code Change Detection

When public API files are modified:

1. Checks if documentation was also updated
2. Adds needs-docs-review label if docs weren't updated
3. Comments on PR prompting for documentation review

Test plan

• Verify workflow file syntax is valid
• Test auto-labeling by creating a PR with code changes
• Test docs validation by modifying documentation

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.33%. Comparing base (ff181b2) to head (76ddce6).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #66   +/-   ##
=======================================
  Coverage   85.33%   85.33%           
=======================================
  Files          18       18           
  Lines        1786     1786           
=======================================
  Hits         1524     1524           
  Misses        262      262           

Flag	Coverage Δ
integration	50.83% <ø> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[claude]

Code Review - Bugs Found

I found 3 bugs in the GitHub Actions workflow that will prevent it from functioning correctly:

---

1. Job conditions will never be true (Lines 19 & 115)

Location:

• Line 19: check-code-changes job
• Line 115: check-docs-changes job

Issue: Both jobs use if: contains(github.event.pull_request.changed_files, ...) which will always evaluate to false.

Why this is a bug:

• github.event.pull_request.changed_files is an integer (count of files), not an array of file paths
• Using contains() on a number to check for a path string always returns false
• These jobs will never execute, breaking the entire workflow

Fix: Remove the if: conditions on lines 19 and 115. The workflow already has a paths: filter in the trigger (lines 5-9) that correctly filters PRs.

Reference:

zae-limiter/.github/workflows/claude-docs-review.yml

Lines 16 to 20 in 76ddce6

	check-code-changes:
	name: Check if code changes need docs updates
	runs-on: ubuntu-latest
	if: contains(github.event.pull_request.changed_files, 'src/zae_limiter/')

---

2. Exit code check captures wrong command (Line 141)

Location: Line 141 in check-docs-changes job

Issue: The exit code check captures the wrong command in the pipeline.

Why this is a bug:

• Line 138 pipes mkdocs output to tee
• Line 141 checks the exit code, which will be from tee (last in pipeline), not mkdocs
• Since tee almost always succeeds, documentation build failures will be marked as successful
• The build validation logic is completely broken

Fix: Add set -o pipefail at the start of the run block to propagate mkdocs exit code through the pipeline.

Reference:

zae-limiter/.github/workflows/claude-docs-review.yml

Lines 134 to 145 in 76ddce6

	- name: Build documentation
	id: build-docs
	run: |
	# Build in strict mode to catch broken links and missing references
	uv run mkdocs build --strict 2>&1 | tee build.log
	# Check if build succeeded
	if [ $? -eq 0 ]; then
	echo "build_success=true" >> $GITHUB_OUTPUT
	else
	echo "build_success=false" >> $GITHUB_OUTPUT
	fi

---

3. Using system Python instead of uv virtual environment (Line 165)

Location: Line 165 in check-docs-changes job

Issue: Uses python3 directly instead of uv run python3.

Why this is a bug:

• Line 132 installs zae_limiter via uv sync into a virtual environment
• Line 165 uses bare python3, which invokes the system Python
• System Python does not have access to packages in uv virtual environment
• The import check will fail with ModuleNotFoundError even when the package is correctly installed

Fix: Change line 165 to use uv run python3 to execute within the virtual environment.

Reference:

zae-limiter/.github/workflows/claude-docs-review.yml

Lines 161 to 179 in 76ddce6

	- name: Check for API signature changes
	id: check-signatures
	run: |
	# Basic check: ensure documented classes/methods exist
	python3 << 'EOF'
	import sys
	try:
	from zae_limiter import (
	RateLimiter, SyncRateLimiter,
	Limit, Entity, LimitStatus, BucketState,
	RateLimitExceeded, RateLimiterUnavailable,
	FailureMode
	)
	print("✅ All documented exports are available")
	sys.exit(0)
	except ImportError as e:
	print(f"❌ Import error: {e}")
	sys.exit(1)
	EOF

---

Summary

All three bugs prevent the workflow from functioning as intended:

1. Jobs never run due to incorrect conditional logic
2. Build failures go undetected due to wrong exit code capture
3. Import checks fail due to wrong Python environment

Please fix these issues before merging.