Add a documentation review tool to identify and manage potentially outdated markdown documentation across BigBang GitLab projects.

Problem

Documentation across BigBang packages, maintained projects, sandbox, and the umbrella repository can become stale over time. There is no automated way to:

• Identify markdown files that haven't been updated in a specified timeframe
• Create tracking issues for documentation review
• Assign issues to appropriate teams based on project ownership
• Group related documentation updates into epics

Solution

Create a unified doc-review.sh script that:

1. Scans for outdated documentation - Searches GitLab groups/projects for markdown files older than a configurable threshold (default: 6 months)

2. Creates tracking issues - Automatically creates GitLab issues for files needing review with appropriate labels and team assignments

3. Supports flexible project selection:

   • --packages - Scan big-bang/product/packages
   • --maintained - Scan big-bang/product/maintained
   • --sandbox - Scan big-bang/apps/sandbox
   • --umbrella - Scan big-bang/bigbang

4. Smart issue grouping:

   • Package/Maintained/Sandbox: 1 issue per file
   • Umbrella: 1 issue per directory (reduces backlog clutter)

5. Epic integration - Optionally add created issues to a specified epic

6. Idempotent operation - Safe to run multiple times; skips existing issues

7. Dry-run mode - Preview changes before execution

Features

• Configurable time threshold (-t, --time MONTHS)
• File count limits per group (-c, --count NUMBER)
• Team filtering (--team TEAM)
• Commit ignore list for refactoring commits (--ignore-commit SHA)
• Input file mode for retrying/reviewing scans (-i, --input FILE)
• Automatic exclusions for chart/, blog/, and adr/ directories
• Dynamic branch detection (master vs main) for accurate file links

Acceptance Criteria

• Script scans specified GitLab groups/projects for markdown files
• Files older than threshold are identified with accurate age calculation
• Issues are created with correct labels (kind::docs, priority::3, team label)
• Umbrella project issues group files by directory
• Dry-run mode shows what would be created without making changes
• Duplicate issues are detected and skipped
• Epic integration adds issues to specified epic
• All project flag combinations work correctly