audit(#662): Issue creation documentation audit and consolidation strategy#702
Conversation
- Identified 55% content overlap across 6 documentation files - Quantified duplication: ~108 lines (~2,400 tokens) - Created consolidation strategy: reduce 6 files to 3 with clear roles * docs/ISSUE_CREATION_GUIDE.md (for issue creators) * docs/ISSUE_TYPES.md (reference) * .github/instructions/issues.instructions.md (for agents/automation) - Proposed deletion: docs/index.md (stub), .github/ISSUE_TEMPLATE/README.md (merge into guide) - Identified 4 broken/incorrect cross-references - Provided validation checklist for consolidation implementation - Report: .github/reports/audits/issue-creation-docs-audit-report.md https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
|
Warning Review limit reached
More reviews will be available in 34 minutes and 9 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🔍 Reviewer Summary for PR #702CI Status: ✅ Recommendations
|
github-actions
Bot
added
type:bug
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a comprehensive audit report evaluating six overlapping issue creation documentation files to identify duplication and propose a consolidation strategy. The review feedback correctly identifies a schema validation issue with the frontmatter's file_type and points out two broken relative paths in the cross-reference analysis section that need to be corrected to properly reference the root docs/ directory.
| @@ -0,0 +1,534 @@ | |||
| --- | |||
| file_type: "audit-report" | |||
There was a problem hiding this comment.
The frontmatter specifies file_type: "audit-report". However, according to the unified frontmatter schema (schema/frontmatter.schema.json), "audit-report" is not a valid or recognized file_type. To ensure compliance with the schema and prevent validation failures, please use "documentation" as the file_type.
| file_type: "audit-report" | |
| file_type: "documentation" |
|
|
||
| 1. **TEMPLATE/README.md (line 36):** References `./ISSUE_TEMPLATE/README.md` (circular reference) | ||
| 2. **TEMPLATE/README.md (line 79):** References `../ISSUE_LABELS.md` (does not exist; should be `docs/ISSUE_LABELS.md` or link moved) | ||
| 3. **instructions/issues.instructions.md (line 58):** References `../docs/ISSUE_CREATION_GUIDE.md` (relative path from .github/instructions, should work) |
There was a problem hiding this comment.
The audit report states that ../docs/ISSUE_CREATION_GUIDE.md "should work" as a relative path from .github/instructions/. However, since .github/instructions/ is two levels deep from the root, ../docs/ resolves to .github/docs/ (which does not exist). The correct relative path to reference the root docs/ directory is ../../docs/ISSUE_CREATION_GUIDE.md. Therefore, this link is actually broken and needs correction.
| 3. **instructions/issues.instructions.md (line 58):** References `../docs/ISSUE_CREATION_GUIDE.md` (relative path from .github/instructions, should work) | |
| 3. **instructions/issues.instructions.md (line 58):** References ../docs/ISSUE_CREATION_GUIDE.md (relative path is broken; should be ../../docs/ISSUE_CREATION_GUIDE.md) |
References
- Documentation and governance files in the
docs/directory must use UPPERCASE naming with underscores (e.g.,GOVERNANCE_REVISION_LOG.md), as the lowercase-with-hyphens naming convention applies to other asset types and not todocs/files.
| 1. **TEMPLATE/README.md (line 36):** References `./ISSUE_TEMPLATE/README.md` (circular reference) | ||
| 2. **TEMPLATE/README.md (line 79):** References `../ISSUE_LABELS.md` (does not exist; should be `docs/ISSUE_LABELS.md` or link moved) | ||
| 3. **instructions/issues.instructions.md (line 58):** References `../docs/ISSUE_CREATION_GUIDE.md` (relative path from .github/instructions, should work) | ||
| 4. **instructions/issues.instructions.md (lines 137-138):** References `../docs/LABEL_STRATEGY.md` (need to verify file exists) |
There was a problem hiding this comment.
Similar to the previous point, ../docs/LABEL_STRATEGY.md from .github/instructions/ is a broken link because it resolves to .github/docs/LABEL_STRATEGY.md. It should be corrected to ../../docs/LABEL_STRATEGY.md to properly point to the root docs/ directory.
| 4. **instructions/issues.instructions.md (lines 137-138):** References `../docs/LABEL_STRATEGY.md` (need to verify file exists) | |
| 4. **instructions/issues.instructions.md (lines 137-138):** References ../docs/LABEL_STRATEGY.md (relative path is broken; should be ../../docs/LABEL_STRATEGY.md) |
References
- Documentation and governance files in the
docs/directory must use UPPERCASE naming with underscores (e.g.,GOVERNANCE_REVISION_LOG.md), as the lowercase-with-hyphens naming convention applies to other asset types and not todocs/files.
- Fix frontmatter file_type: change from 'audit-report' to 'documentation' (audit-report not valid in unified frontmatter schema) - Fix broken relative path references to docs/ directory: - Line 370: ../docs/ → ../../docs/ (from .github/instructions context) - Line 371: ../docs/ → ../../docs/ (from .github/instructions context) - Minor file path consistency: ensure all .github/* paths are fully qualified https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- Changed file_type from quoted string to unquoted identifier - Added created_date and last_updated (ISO format) - Replaced audit_date with standard created_date field - Changed auditor to author field - Added tags array with document-specific tags - Added category (governance) and stability (stable) - Changed version from quoted string to number https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- Wrapped description across multiple lines - Added maintainer and owners fields - Changed version format to v1.0 - Reordered fields to match canonical schema https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
There was a problem hiding this comment.
Pull request overview
Adds a single new audit report under .github/reports/audits/ for issue #662. The report inventories six issue-creation documentation files, quantifies duplication (~55% overlap, ~108 lines), flags broken cross-references, and proposes consolidating to three canonical files plus deletion of stubs. No code or existing documentation is modified by this PR.
Changes:
- New 545-line audit report with executive summary, overlap matrix, cross-reference analysis, and a phased consolidation plan
- Consolidation matrix recommending keep/merge/delete actions for each audited file
- Validation checklist and file inventory appendices to guide the follow-up work
| | `docs/ISSUE_CREATION_GUIDE.md` | Practical step-by-step guide | Guidance | 5.3 KB | | ||
| | `docs/ISSUE_TYPES.md` | Canonical reference of 27 issue types | Reference | 11.9 KB | | ||
| | `.github/ISSUE_TEMPLATE/README.md` | Template directory overview | Navigation | 2.8 KB | | ||
| | `.github/instructions/issues.instructions.md` | Rules and automation standards | Instruction | 7.2 KB | |
| **ISSUE_TYPES.md (Entire document, 11.9 KB):** | ||
|
|
||
| - Comprehensive reference of all 27 types | ||
| - Detailed comparison table with colors, use cases, priority |
| 2. **docs/ISSUE_TYPES.md** — *Reference Document* | ||
| - Who: Anyone needing to understand issue types | ||
| - Purpose: Comprehensive reference of 27 types with decision tree | ||
| - Include: All types, use cases, automation behaviors, best practices |
| 5. **docs/README.md** (5.5 KB) | ||
| - Status: Keep (unmodified) | ||
| - Priority: MEDIUM | ||
| - Action: Update index if guide/instructions reorganized |
- Fixed .github/instructions/issues.instructions.md → instructions/issues.instructions.md (root-level directory) - Re-evaluated section 9 broken reference findings (paths are correct from root-level instructions/) - Changed 'colors' → 'colours' (UK English) - Changed 'behaviors' → 'behaviours' (UK English) - Changed 'reorganized' → 'reorganised' (UK English) https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- Changed to quoted field values (matching existing audit reports) - Removed non-standard fields (author, maintainer, category, status, stability) - Used standard frontmatter format from passing audit reports - File now passes frontmatter validation https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- Changed owners from 'lightspeedwp/maintainers' to 'LightSpeed Maintainers' - Ensures exact format match with passing validation schema https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
- Update created_date and last_updated to use single quotes (required for YAML date string parsing) - Add all required frontmatter fields: authors, maintainer, domain, status, language, stability - Change status from 'stable' to 'active' (valid enum value) - Validate frontmatter passes schema constraints https://claude.ai/code/session_01JAbqDKAJZf6prJQhPkkp9b
github-actions
Bot
added
area:scripts
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 92f3b3d7c6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - References: `../.github/ISSUE_TYPES.md` (line 56) | ||
| - Referenced by: docs/README.md (Quick Start & by Task) | ||
| - Quality: Single precise reference to ISSUE_TYPES |
There was a problem hiding this comment.
The audit marks this reference as a precise, good cross-reference, but docs/ISSUE_CREATION_GUIDE.md links to ../.github/ISSUE_TYPES.md, which resolves to .github/ISSUE_TYPES.md from the repo root and that file does not exist; the existing target is docs/ISSUE_TYPES.md. Because this report is meant to drive the consolidation work, classifying this broken link as healthy leaves a concrete navigation defect untracked.
Useful? React with 👍 / 👎.
| 2. **TEMPLATE/README.md (line 79):** References `../ISSUE_LABELS.md` (does not exist; should be `docs/ISSUE_LABELS.md` or link moved) | ||
| 3. **instructions/issues.instructions.md (line 58):** References `../docs/ISSUE_CREATION_GUIDE.md` (correct relative path from root-level instructions/) | ||
| 4. **instructions/issues.instructions.md (lines 137-138):** References `../docs/LABEL_STRATEGY.md` (correct relative path from root-level instructions/) |
There was a problem hiding this comment.
These recommendations still treat docs/ISSUE_LABELS.md and docs/LABEL_STRATEGY.md as valid targets, but I checked the repo and neither file exists; docs/MIGRATION.md and instructions/DEPRECATED.md explicitly say both were consolidated into docs/LABELING.md. If the follow-up consolidation follows this audit, it will preserve or introduce broken label-documentation links instead of fixing them.
Useful? React with 👍 / 👎.
Issue #662: Audit Issue Creation Docs
Summary
Comprehensive audit of 6 overlapping issue creation documentation files to identify duplication and propose consolidation strategy.
Key Findings:
Consolidation Strategy
Proposed structure (6 files → 3 files):
docs/ISSUE_CREATION_GUIDE.md (keep, revise)
docs/ISSUE_TYPES.md (keep, unmodified)
.github/instructions/issues.instructions.md (keep, revise)
Delete:
.github/ISSUE_TEMPLATE/README.md(merge into guide)docs/index.md(stub with no content)Deliverables
.github/reports/audits/issue-creation-docs-audit-report.md(12 KB)Next Steps
Related Issues
Generated by Claude Code