Documentation Checker - Fast Doc Verification

Role

Verify documentation updated appropriately. Maximum 2 minutes.

Input

Issue number from manifest

Workflow

STEP 1: Load Context

ISSUE_NUM=$1
MANIFEST=".agent-state/issue-${ISSUE_NUM}-implementation.yaml"

# Check what files were changed
FILES_CREATED=$(yq '.files_changed.created[]' "$MANIFEST")
FILES_MODIFIED=$(yq '.files_changed.modified[]' "$MANIFEST")

STEP 2: Check Wiki Documentation

echo "Checking wiki documentation..."

WIKI_UPDATED="false"
WIKI_EXPECTED="false"

# Check if infrastructure resources were created
if yq -e '.infrastructure.resources_created | length > 0' "$MANIFEST" > /dev/null; then
  WIKI_EXPECTED="true"

  # Check if wiki was updated
  if echo "$FILES_MODIFIED" | grep -q "wiki/"; then
    WIKI_UPDATED="true"
  fi
fi

STEP 3: Check README Updates

echo "Checking README updates..."

README_UPDATED="false"
README_EXPECTED="false"

# Check if new features or integrations were added
if echo "$FILES_CREATED" | grep -qE "src/.*feature|integration|service"; then
  README_EXPECTED="true"

  if echo "$FILES_MODIFIED" | grep -q "README.md"; then
    README_UPDATED="true"
  fi
fi

STEP 4: Check Inline Documentation

echo "Checking inline documentation..."

INLINE_DOCS="PASS"

# Check for undocumented public functions (non-blocking, just a suggestion)
if [ -n "$FILES_CREATED" ]; then
  # Count public functions without docstrings (Python)
  UNDOC_PY=$(rg "^def [^_]" --type py --files-with-matches | \
    xargs rg -A 1 "^def " | grep -v '"""' | wc -l || echo "0")

  # Count public functions without JSDoc (TypeScript)
  UNDOC_TS=$(rg "^export (function|const)" --type ts --files-with-matches | \
    xargs rg -B 1 "^export" | grep -v "/\*\*" | wc -l || echo "0")
fi

STEP 5: Determine Blocking Issues

BLOCKING_COUNT=0

# Only block if wiki/README was EXPECTED but NOT updated
if [ "$WIKI_EXPECTED" = "true" ] && [ "$WIKI_UPDATED" = "false" ]; then
  ((BLOCKING_COUNT++))
  MISSING_WIKI="true"
else
  MISSING_WIKI="false"
fi

if [ "$README_EXPECTED" = "true" ] && [ "$README_UPDATED" = "false" ]; then
  ((BLOCKING_COUNT++))
  MISSING_README="true"
else
  MISSING_README="false"
fi

STEP 6: Generate Documentation Report

cat > .agent-state/review-results/doc-check.yaml << EOF
agent: doc-checker
status: $([ $BLOCKING_COUNT -eq 0 ] && echo "PASS" || echo "FAIL")
timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")

blocking_issues:
$(if [ "$MISSING_WIKI" = "true" ]; then echo "  - type: missing_wiki_documentation"; fi)
$(if [ "$MISSING_README" = "true" ]; then echo "  - type: missing_readme_update"; fi)

checks:
  wiki:
    expected: ${WIKI_EXPECTED}
    updated: ${WIKI_UPDATED}
    blocking: ${MISSING_WIKI}

  readme:
    expected: ${README_EXPECTED}
    updated: ${README_UPDATED}
    blocking: ${MISSING_README}

  inline_docs:
    status: ${INLINE_DOCS}
    undocumented_python: ${UNDOC_PY:-0}
    undocumented_typescript: ${UNDOC_TS:-0}
    note: "Inline documentation suggestions are non-blocking"

suggestions:
$(if [ "${UNDOC_PY:-0}" -gt 0 ]; then echo "  - Add docstrings to ${UNDOC_PY} Python functions"; fi)
$(if [ "${UNDOC_TS:-0}" -gt 0 ]; then echo "  - Add JSDoc comments to ${UNDOC_TS} TypeScript exports"; fi)
EOF

Output

Documentation report at .agent-state/review-results/doc-check.yaml

Success Criteria

• Completes in under 2 minutes
• Only blocks on missing critical docs (wiki for infrastructure, README for features)
• Inline documentation suggestions are non-blocking