Add documentation review packet for external Claude review
Review packet used for fresh Claude instances to evaluate documentation system structure and efficiency. Contains: - Git API access instructions - Review criteria (organization, redundancy, scalability) - Output format specification - Instructions for unbiased structural review Used for: - Fresh Claude review #1 (Feb 16, 2026) - Rating: NEEDS WORK - Fresh Claude review #2 (Feb 16, 2026) - After restructure Stored for future documentation audits. Date: February 16, 2026 Created by: The Chronicler
This commit is contained in:
466
docs/reference/documentation-review-packet.md
Normal file
466
docs/reference/documentation-review-packet.md
Normal file
@@ -0,0 +1,466 @@
|
||||
# Documentation System Review Packet
|
||||
## For Fresh Claude Instance
|
||||
|
||||
---
|
||||
|
||||
# PART 1: YOUR ROLE & GIT ACCESS
|
||||
|
||||
## Your Mission
|
||||
|
||||
You are reviewing the **documentation system** for Firefrost Gaming's operations manual. Your job is to analyze **structure, organization, and efficiency** — NOT to rewrite content or implement changes.
|
||||
|
||||
**What you're evaluating:**
|
||||
- Document organization and structure
|
||||
- Naming conventions and discoverability
|
||||
- Redundancy and duplication
|
||||
- Scalability (will this work with 50+ tasks?)
|
||||
- Maintainability (easy to keep current?)
|
||||
- Navigation and usability
|
||||
|
||||
**What you're NOT doing:**
|
||||
- Rewriting documents
|
||||
- Implementing changes
|
||||
- Making it "more corporate" or "professional"
|
||||
- Removing personality (intentional design choice)
|
||||
- Critiquing relationship/emotional content (out of scope)
|
||||
|
||||
---
|
||||
|
||||
## Git Repository Access
|
||||
|
||||
You'll need to pull files from the Firefrost Gaming operations manual repository to conduct your review.
|
||||
|
||||
**Repository Details:**
|
||||
- **Base URL:** `https://git.firefrostgaming.com`
|
||||
- **Repository:** `firefrost-gaming/firefrost-operations-manual`
|
||||
- **Branch:** `master`
|
||||
|
||||
### Git API Commands (Proven Working)
|
||||
|
||||
**⚠️ CRITICAL: Use these exact commands. They are tested and verified.**
|
||||
|
||||
#### List Repository Contents
|
||||
```bash
|
||||
curl -s -H "Authorization: token YOUR_TOKEN_HERE" \
|
||||
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents?ref=master"
|
||||
```
|
||||
|
||||
Returns JSON array of files/directories in root.
|
||||
|
||||
#### Get a Specific File
|
||||
```bash
|
||||
curl -s -H "Authorization: token YOUR_TOKEN_HERE" \
|
||||
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/PATH/TO/FILE.md?ref=master"
|
||||
```
|
||||
|
||||
Replace `PATH/TO/FILE.md` with actual file path (e.g., `docs/core/tasks.md`).
|
||||
|
||||
Returns JSON:
|
||||
```json
|
||||
{
|
||||
"content": "BASE64_ENCODED_CONTENT_HERE",
|
||||
"sha": "commit_hash",
|
||||
"size": file_size_bytes,
|
||||
"name": "filename.md",
|
||||
"path": "full/path/to/file.md"
|
||||
}
|
||||
```
|
||||
|
||||
#### Decode File Content
|
||||
The `content` field is base64-encoded. Decode using:
|
||||
|
||||
```python
|
||||
import base64
|
||||
import json
|
||||
|
||||
# After getting the JSON response
|
||||
data = json.loads(response_text)
|
||||
content = base64.b64decode(data['content']).decode('utf-8')
|
||||
print(content)
|
||||
```
|
||||
|
||||
#### List Directory Contents
|
||||
```bash
|
||||
curl -s -H "Authorization: token YOUR_TOKEN_HERE" \
|
||||
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/contents/docs/tasks?ref=master"
|
||||
```
|
||||
|
||||
Replace `docs/tasks` with any directory path.
|
||||
|
||||
#### Get Full Repository Tree (Recursive)
|
||||
```bash
|
||||
curl -s -H "Authorization: token YOUR_TOKEN_HERE" \
|
||||
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/git/trees/master?recursive=1"
|
||||
```
|
||||
|
||||
Returns complete file tree in JSON. Useful for seeing overall structure.
|
||||
|
||||
---
|
||||
|
||||
## Review Workflow
|
||||
|
||||
**Step 1: Receive Token**
|
||||
The user will paste the Gitea API token in their next message.
|
||||
|
||||
**Step 2: Start with Structure**
|
||||
```bash
|
||||
# Get repository tree to see overall structure
|
||||
curl -s -H "Authorization: token TOKEN_HERE" \
|
||||
"https://git.firefrostgaming.com/api/v1/repos/firefrost-gaming/firefrost-operations-manual/git/trees/master?recursive=1"
|
||||
```
|
||||
|
||||
**Step 3: Read Key Documents**
|
||||
1. `DOCUMENT-INDEX.md` - Repository map
|
||||
2. `docs/standards/task-documentation-standard.md` - The system you're reviewing
|
||||
3. `docs/core/tasks.md` - Master task list
|
||||
4. `docs/tasks/whitelist-manager/deployment-plan.md` - Example task documentation
|
||||
|
||||
**Step 4: Browse Structure**
|
||||
- Examine `docs/tasks/` directory
|
||||
- Check `docs/core/` organization
|
||||
- Review `docs/standards/` structure
|
||||
- Look at `docs/troubleshooting/`
|
||||
- Check for orphaned files
|
||||
|
||||
**Step 5: Analyze & Report**
|
||||
Provide findings using the format specified in Part 3.
|
||||
|
||||
---
|
||||
|
||||
## Ready for Token?
|
||||
|
||||
Confirm you're ready, and the user will provide the Gitea API token.
|
||||
|
||||
Once you have it, begin your review starting with the repository structure.
|
||||
|
||||
---
|
||||
|
||||
# PART 2: REVIEW CRITERIA
|
||||
|
||||
## What to Analyze
|
||||
|
||||
### 1. Document Organization
|
||||
**Questions:**
|
||||
- Is the directory structure logical and intuitive?
|
||||
- Are files grouped sensibly?
|
||||
- Is there a clear hierarchy?
|
||||
- Can someone new navigate without getting lost?
|
||||
- Are naming conventions consistent?
|
||||
|
||||
**Look for:**
|
||||
- Confusing directory names
|
||||
- Inconsistent file naming
|
||||
- Files in wrong locations
|
||||
- Missing organizational logic
|
||||
- Unclear hierarchy
|
||||
|
||||
---
|
||||
|
||||
### 2. Redundancy & Duplication
|
||||
**Questions:**
|
||||
- Is information repeated across multiple files?
|
||||
- Are there overlapping documents?
|
||||
- Could any files be merged without loss of clarity?
|
||||
- Are updates required in multiple places?
|
||||
|
||||
**Look for:**
|
||||
- Same procedures in multiple documents
|
||||
- Duplicate configuration examples
|
||||
- Repeated prerequisite lists
|
||||
- Information that could be centralized
|
||||
|
||||
---
|
||||
|
||||
### 3. Discoverability
|
||||
**Questions:**
|
||||
- Can you find what you need quickly?
|
||||
- Are naming conventions intuitive?
|
||||
- Do documents link to related content?
|
||||
- Is there a clear entry point for different use cases?
|
||||
|
||||
**Look for:**
|
||||
- Unclear file names (what does this contain?)
|
||||
- Missing cross-references
|
||||
- No index or table of contents
|
||||
- Hard to find related documentation
|
||||
|
||||
---
|
||||
|
||||
### 4. Scalability
|
||||
**Questions:**
|
||||
- Will this structure work with 50+ tasks?
|
||||
- Will this work with 100+ tasks?
|
||||
- Does adding new tasks create clutter?
|
||||
- Is there a sustainable growth pattern?
|
||||
|
||||
**Look for:**
|
||||
- Flat directories that will become unwieldy
|
||||
- No categorization strategy
|
||||
- Task list that will become unmanageable
|
||||
- Lack of archival strategy
|
||||
|
||||
---
|
||||
|
||||
### 5. Maintainability
|
||||
**Questions:**
|
||||
- How easy is it to update information?
|
||||
- Are changes localized or scattered?
|
||||
- Is there a single source of truth?
|
||||
- Can you tell what's current vs deprecated?
|
||||
|
||||
**Look for:**
|
||||
- Information duplicated across files
|
||||
- No version indicators
|
||||
- No "last updated" dates
|
||||
- Unclear deprecation strategy
|
||||
- Scattered related information
|
||||
|
||||
---
|
||||
|
||||
### 6. Clarity & Usability
|
||||
**Questions:**
|
||||
- Are document purposes clear from their names?
|
||||
- Is the standard (task-documentation-standard.md) clear?
|
||||
- Are templates provided where needed?
|
||||
- Is there adequate documentation of the documentation system itself?
|
||||
|
||||
**Look for:**
|
||||
- Unclear document purposes
|
||||
- Missing templates
|
||||
- Inadequate meta-documentation
|
||||
- Confusing conventions
|
||||
|
||||
---
|
||||
|
||||
### 7. Efficiency
|
||||
**Questions:**
|
||||
- Is there over-documentation (too much detail)?
|
||||
- Is there under-documentation (critical gaps)?
|
||||
- Are procedures at the right level of detail?
|
||||
- Is navigation efficient?
|
||||
|
||||
**Look for:**
|
||||
- Documents that are too long
|
||||
- Missing critical procedures
|
||||
- Too many clicks to find information
|
||||
- Excessive nesting
|
||||
|
||||
---
|
||||
|
||||
### 8. Technical Issues
|
||||
**Questions:**
|
||||
- Are there broken links?
|
||||
- Are there orphaned files?
|
||||
- Are there missing files referenced elsewhere?
|
||||
- Is the file structure Git-friendly?
|
||||
|
||||
**Look for:**
|
||||
- Links to non-existent files
|
||||
- Files not referenced anywhere
|
||||
- Inconsistent path references
|
||||
- Issues that would break Git operations
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
**DO NOT review:**
|
||||
- Content quality (assume content is correct)
|
||||
- Writing style or tone
|
||||
- Relationship/emotional documentation (THE-JOINING-PROTOCOL.md, THE-ESSENCE-PATCH.md, etc.)
|
||||
- Technical accuracy of procedures
|
||||
- Whether specific tools/technologies are the right choice
|
||||
|
||||
**FOCUS ONLY ON:**
|
||||
- Structure
|
||||
- Organization
|
||||
- Efficiency
|
||||
- Scalability
|
||||
- Maintainability
|
||||
|
||||
---
|
||||
|
||||
# PART 3: OUTPUT FORMAT
|
||||
|
||||
Provide your findings in this structured format:
|
||||
|
||||
---
|
||||
|
||||
## DOCUMENTATION SYSTEM REVIEW
|
||||
**Reviewed by:** Claude (Fresh Instance)
|
||||
**Date:** [Today's date]
|
||||
**Repository:** firefrost-gaming/firefrost-operations-manual
|
||||
**Scope:** Documentation structure and organization
|
||||
|
||||
---
|
||||
|
||||
### EXECUTIVE SUMMARY
|
||||
[2-3 paragraphs summarizing overall findings]
|
||||
- Overall assessment (Strong/Good/Needs Work)
|
||||
- Top 3 strengths of current system
|
||||
- Top 3 areas for improvement
|
||||
- General recommendation (minor tweaks vs major restructure)
|
||||
|
||||
---
|
||||
|
||||
### DETAILED FINDINGS
|
||||
|
||||
#### 1. STRUCTURAL ISSUES
|
||||
|
||||
**Issue:** [Description of structural problem]
|
||||
- **Location:** [Where in the repo]
|
||||
- **Impact:** [How this affects usability/maintainability]
|
||||
- **Suggestion:** [Specific improvement]
|
||||
- **Priority:** [High/Medium/Low]
|
||||
- **Effort:** [Low/Medium/High to fix]
|
||||
|
||||
[Repeat for each structural issue found]
|
||||
|
||||
---
|
||||
|
||||
#### 2. REDUNDANCIES FOUND
|
||||
|
||||
**Redundancy:** [Description of duplication]
|
||||
- **Files affected:** [List of files]
|
||||
- **Impact:** [Risk of inconsistency, maintenance burden]
|
||||
- **Suggestion:** [How to consolidate]
|
||||
- **Priority:** [High/Medium/Low]
|
||||
|
||||
[Repeat for each redundancy]
|
||||
|
||||
---
|
||||
|
||||
#### 3. NAVIGATION & DISCOVERABILITY
|
||||
|
||||
**Issue:** [Navigation difficulty]
|
||||
- **Scenario:** [When someone tries to...]
|
||||
- **Problem:** [What makes it hard]
|
||||
- **Suggestion:** [How to improve]
|
||||
- **Priority:** [High/Medium/Low]
|
||||
|
||||
[Repeat for each discoverability issue]
|
||||
|
||||
---
|
||||
|
||||
#### 4. SCALABILITY CONCERNS
|
||||
|
||||
**Concern:** [What won't scale well]
|
||||
- **Current state:** [Works now because...]
|
||||
- **Future problem:** [At N tasks/docs, this will...]
|
||||
- **Suggestion:** [How to make it scale]
|
||||
- **Priority:** [High/Medium/Low]
|
||||
|
||||
[Repeat for each scalability concern]
|
||||
|
||||
---
|
||||
|
||||
#### 5. MAINTAINABILITY ISSUES
|
||||
|
||||
**Issue:** [What makes maintenance hard]
|
||||
- **Current workflow:** [How updates work now]
|
||||
- **Problem:** [Why this is inefficient/error-prone]
|
||||
- **Suggestion:** [Better approach]
|
||||
- **Priority:** [High/Medium/Low]
|
||||
|
||||
[Repeat for each maintainability issue]
|
||||
|
||||
---
|
||||
|
||||
#### 6. EFFICIENCY IMPROVEMENTS
|
||||
|
||||
**Opportunity:** [Where efficiency can improve]
|
||||
- **Current approach:** [How it works now]
|
||||
- **Cost:** [Time/effort/confusion]
|
||||
- **Suggestion:** [More efficient approach]
|
||||
- **Benefit:** [Time saved/clarity gained]
|
||||
- **Priority:** [High/Medium/Low]
|
||||
|
||||
[Repeat for each efficiency opportunity]
|
||||
|
||||
---
|
||||
|
||||
#### 7. TECHNICAL ISSUES
|
||||
|
||||
**Issue:** [Broken link, orphan file, etc.]
|
||||
- **Location:** [Specific file/path]
|
||||
- **Problem:** [What's broken]
|
||||
- **Fix:** [How to correct]
|
||||
- **Priority:** [High/Medium/Low]
|
||||
|
||||
[Repeat for each technical issue]
|
||||
|
||||
---
|
||||
|
||||
### POSITIVE OBSERVATIONS
|
||||
|
||||
**Strengths of Current System:**
|
||||
- [Strength 1]
|
||||
- [Strength 2]
|
||||
- [Strength 3]
|
||||
|
||||
**Things NOT to change:**
|
||||
- [What's working well 1]
|
||||
- [What's working well 2]
|
||||
|
||||
---
|
||||
|
||||
### PRIORITIZED RECOMMENDATIONS
|
||||
|
||||
#### HIGH Priority (Do First)
|
||||
1. [Recommendation with biggest impact]
|
||||
2. [Next most important]
|
||||
3. [...]
|
||||
|
||||
#### MEDIUM Priority (Do Soon)
|
||||
1. [Recommendation]
|
||||
2. [...]
|
||||
|
||||
#### LOW Priority (Nice to Have)
|
||||
1. [Recommendation]
|
||||
2. [...]
|
||||
|
||||
---
|
||||
|
||||
### IMPLEMENTATION NOTES
|
||||
|
||||
**Quick Wins** (< 1 hour):
|
||||
- [Easy fix 1]
|
||||
- [Easy fix 2]
|
||||
|
||||
**Moderate Effort** (1-3 hours):
|
||||
- [Medium fix 1]
|
||||
- [Medium fix 2]
|
||||
|
||||
**Major Refactor** (3+ hours or requires planning):
|
||||
- [Large change 1]
|
||||
- [Large change 2]
|
||||
|
||||
---
|
||||
|
||||
### QUESTIONS FOR CLARIFICATION
|
||||
|
||||
If you need more context to provide better recommendations:
|
||||
- [Question 1]
|
||||
- [Question 2]
|
||||
|
||||
---
|
||||
|
||||
## END OF REVIEW
|
||||
|
||||
---
|
||||
|
||||
# IMPORTANT REMINDERS
|
||||
|
||||
1. **DO NOT rewrite documents** - only suggest changes
|
||||
2. **DO NOT implement** - only recommend
|
||||
3. **Focus on STRUCTURE** not content
|
||||
4. **Be specific** - provide file paths and concrete suggestions
|
||||
5. **Prioritize** - not everything is equally important
|
||||
6. **Consider the user** - they have hand surgery limitations, need clear navigation
|
||||
7. **Respect the system** - relationship docs are intentionally different, don't "fix" them
|
||||
|
||||
**Your goal:** Help make this documentation system more efficient, maintainable, and scalable while respecting its unique character.
|
||||
|
||||
---
|
||||
|
||||
**Ready for the Gitea API token?**
|
||||
Reference in New Issue
Block a user