القائمة
Organize, update, and enrich project documentation through checkpoint-driven audits and post-implementation updates ensuring consistency and completeness
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Implements database migrations using checkpoint-driven approach with verification at each step to ensure safe schema changes and data integrity
Data-driven sprint planning and retrospective analysis for Gastrobrain using GitHub Project #3 issues, historical velocity patterns, and sprint estimation diary insights. Generates realistic sprint plans with capacity analysis, sequencing strategy, and risk assessment. Conducts structured sprint retrospectives with developer interviews, estimation accuracy analysis, and diary entry generation.
Execute Phase 1 (Analysis & Understanding) of issue roadmaps through systematic 5-checkpoint technical analysis
Generates actionable, phase-based implementation roadmaps for GitHub issues. Creates comprehensive markdown documents with checkbox lists for analysis, implementation, testing, and documentation phases. Applies Gastrobrain-specific testing, localization, and database conventions automatically.
Strategic partner for roadmap planning, priority setting, and project health management. Provides 'wide picture' perspective balancing feature development with code quality, technical debt, and long-term sustainability. Use for: 'Review the roadmap', 'Help me prioritize', 'Is my milestone balanced?', 'Should I focus on features or quality?', 'Strategic review of 0.X.Y'.
User experience design specialist for Gastrobrain. Analyzes user goals, maps flows, designs information architecture, creates wireframes, and ensures accessibility before implementation. Reinforces 'Cultured & Flavorful' design identity. Use when: 'Design the UX for #XXX', 'Help me redesign [screen]', 'What should the user flow be?', 'I need wireframes for #XXX', 'Think through the information architecture'.
| name | gastrobrain-documentation-master |
| description | Organize, update, and enrich project documentation through checkpoint-driven audits and post-implementation updates ensuring consistency and completeness |
| version | 1.0.0 |
| author | Gastrobrain Development Team |
| tags | ["documentation","technical-writing","architecture","maintenance","quality"] |
This skill maintains project documentation quality through systematic checkpoint-driven processes. It acts as a technical writer who audits existing documentation, identifies gaps, updates content after code changes, creates missing documentation, and enforces consistency standards across the entire project.
Core philosophy: Documentation is a maintained asset, not an afterthought. Every code change should have corresponding documentation updates, and all documentation should be organized, discoverable, and accurate.
Trigger phrases:
Use cases:
What this skill provides:
A Technical Writer perspective that:
Gastrobrain-specific requirements:
Reference documentation is written in self-contained HTML. Workflow and process docs stay as Markdown.
| Document Type | Format | Location |
|---|---|---|
| Architecture overviews | HTML | docs/architecture/ |
| Roadmaps & status | HTML | docs/archive/ |
| Feature guides | HTML | docs/guides/ |
| Design system docs | HTML | docs/design/ |
| Skills master index | HTML | docs/architecture/ |
| Workflow process docs | Markdown | docs/workflows/ |
| Testing guides | Markdown | docs/testing/ |
| Sprint planning (working) | Markdown | docs/planning/sprints/ |
| Skill prompts | Markdown | .claude/skills/*/SKILL.md |
| CLAUDE.md / AI context | Markdown | repo root / lib/ |
| Code comments | Dartdoc | lib/ source files |
HTML document rules:
<style>, no external dependencies#d97706) / green (#065f46) palette matching the Gastrobrain design identity.md file already exists, the .html companion lives alongside it and is the primary human-readable versiondocs/archive/Gastrobrain-Roadmap-Status.html and docs/architecture/Gastrobrain-Codebase-Overview.html| Type | Location | Format | Purpose |
|---|---|---|---|
| Project Overview | README.md | Markdown | First impression, quick start |
| Architecture | docs/architecture/ | HTML | System design, data models |
| Roadmap & Status | docs/archive/ | HTML | Milestone tracking |
| Workflow Guides | docs/workflows/ | Markdown | Development processes |
| Testing Guides | docs/testing/ | Markdown | Test patterns and helpers |
| Planning (working) | docs/planning/sprints/ | Markdown | Sprint notes |
| Feature Guides | docs/guides/ | HTML | Individual feature docs |
| Pattern Docs | docs/patterns/ | HTML | Reusable design patterns |
| Decision Records | docs/decisions/ | HTML | ADRs for key decisions |
| Code Comments | lib/ | Dartdoc | Dartdoc in source files |
| Skill Docs | .claude/skills/ | Markdown | Agent skill documentation |
Use when: Performing a comprehensive review of all project documentation.
Trigger: "Audit project documentation"
|
Checkpoint 1: Inventory Existing Documentation (WAIT)
|
Checkpoint 2: Gap Analysis (WAIT)
|
Checkpoint 3: Structure Assessment (WAIT)
|
Checkpoint 4: Quality Review (WAIT)
|
Checkpoint 5: Improvement Plan (WAIT)
|
Checkpoint 6: Execute Priority Updates (WAIT)
|
Documentation Audit Complete
Purpose: Catalog all documentation files and assess their current state.
Actions:
Output format:
Documentation Audit
CHECKPOINT 1: Inventory Existing Documentation
───────────────────────────────────────────────
Scanning documentation locations...
📂 Root Level
- README.md [Last modified: YYYY-MM-DD] [Status: Complete/Partial/Outdated]
- CLAUDE.md [Last modified: YYYY-MM-DD] [Status: Complete]
- CHANGELOG.md [Status: Missing/Present]
📂 docs/architecture/
- overview.md [Status: ...]
- data-model.md [Status: ...]
[...]
📂 docs/workflows/
- ISSUE_WORKFLOW.md [Status: ...]
[...]
📂 docs/testing/
- DIALOG_TESTING_GUIDE.md [Status: ...]
[...]
📂 docs/planning/
[...]
📂 .claude/skills/
[list each skill with README status]
📂 lib/ (code documentation)
- [Assessment of dartdoc coverage in key files]
Summary:
- Total files found: XX
- Complete: XX
- Partial: XX
- Outdated: XX
- Missing (expected): XX
Inventory complete? Any files I missed? (y/n/add)
Wait for user response before proceeding.
Purpose: Compare code vs documentation and find undocumented features.
Actions:
Output format:
───────────────────────────────────────────────
CHECKPOINT 2: Gap Analysis
Comparing codebase against documentation...
🔴 CRITICAL GAPS (blocking understanding):
- [ ] [Gap 1 - e.g., "No architecture overview for recommendation engine"]
- [ ] [Gap 2 - e.g., "Service layer undocumented"]
🟡 IMPORTANT GAPS (hinders development):
- [ ] [Gap 1 - e.g., "Widget patterns not documented"]
- [ ] [Gap 2 - e.g., "State management approach unclear"]
🟢 NICE-TO-HAVE GAPS (improves experience):
- [ ] [Gap 1 - e.g., "Feature screenshots outdated"]
- [ ] [Gap 2 - e.g., "Code examples limited"]
🔵 OUTDATED CONTENT:
- [ ] [Item 1 - e.g., "README mentions old sprint system"]
- [ ] [Item 2 - e.g., "Architecture diagram shows old structure"]
🔍 INCONSISTENCIES:
- [ ] [Item 1 - e.g., "Terminology varies across docs"]
- [ ] [Item 2 - e.g., "Code examples use different patterns"]
Feature Documentation Coverage:
| Feature | Code | Docs | Status |
|---------|------|------|--------|
| Recipes | ✓ | ✓ | Current |
| Meal Planning | ✓ | Partial | Needs update |
| Recommendations | ✓ | ✗ | Missing |
| [etc.] | | | |
Gap analysis complete? Anything I missed? (y/n/add)
Wait for user response before proceeding.
Purpose: Evaluate documentation organization and discoverability.
Actions:
Output format:
───────────────────────────────────────────────
CHECKPOINT 3: Structure Assessment
Current Structure:
[Show current docs/ tree]
Ideal Structure:
[Show recommended docs/ tree - see Organization Structure section]
Assessment:
📁 Organization: [Good/Needs Work/Poor]
- [Specific finding 1]
- [Specific finding 2]
🔗 Cross-References: [Good/Needs Work/Poor]
- [Link status 1]
- [Link status 2]
🧭 Discoverability: [Good/Needs Work/Poor]
- [Finding 1 - can developers find testing docs?]
- [Finding 2 - is architecture clearly navigable?]
📄 Misplaced Documents:
- [File] → Should move from [current] to [recommended]
Structural Recommendations:
1. [Recommendation 1]
2. [Recommendation 2]
3. [Recommendation 3]
Structure assessment complete? (y/n/discuss)
Wait for user response before proceeding.
Purpose: Check documentation clarity, accuracy, and examples.
Actions:
Output format:
───────────────────────────────────────────────
CHECKPOINT 4: Quality Review
Reviewing documentation quality...
📝 Clarity Assessment:
- README.md: [Clear/Needs Improvement] - [specific note]
- [Key doc 1]: [Clear/Needs Improvement] - [specific note]
- [Key doc 2]: [Clear/Needs Improvement] - [specific note]
💻 Code Examples:
- [Doc 1]: [X/Y examples verified current]
- [Doc 2]: [X/Y examples verified current]
- Outdated examples found: [list]
🔗 Link Verification:
- Internal links: [X/Y working]
- Broken links: [list]
- External links: [X/Y working]
📋 Accuracy Check:
- [Doc 1]: [Accurate/Outdated] - [detail]
- [Doc 2]: [Accurate/Outdated] - [detail]
📐 Formatting:
- Consistent heading styles: [Yes/No]
- Code blocks properly formatted: [Yes/No]
- Tables readable: [Yes/No]
Quality review complete? (y/n/focus on specific area)
Wait for user response before proceeding.
Purpose: Prioritize and plan documentation updates.
Actions:
Output format:
───────────────────────────────────────────────
CHECKPOINT 5: Improvement Plan
Based on the audit findings, here's the prioritized plan:
🔴 PRIORITY 1 - Critical Updates (do now):
1. [ ] [Task] - Est: [X hours] - Impact: [why critical]
2. [ ] [Task] - Est: [X hours] - Impact: [why critical]
🟡 PRIORITY 2 - Important Updates (do soon):
3. [ ] [Task] - Est: [X hours] - Impact: [why important]
4. [ ] [Task] - Est: [X hours] - Impact: [why important]
🟢 PRIORITY 3 - Nice-to-Have (do later):
5. [ ] [Task] - Est: [X hours] - Impact: [improvement]
6. [ ] [Task] - Est: [X hours] - Impact: [improvement]
Total Estimated Effort: [X hours]
Recommended approach:
- Sprint 1: Priority 1 items ([X hours])
- Sprint 2: Priority 2 items ([X hours])
- Backlog: Priority 3 items
Which items should we tackle now? (all P1/specific items/custom selection)
Wait for user response before proceeding.
Purpose: Implement the approved documentation improvements.
Actions:
Output format:
───────────────────────────────────────────────
CHECKPOINT 6: Execute Priority Updates
Executing approved documentation improvements...
Task 1: [Description]
─────────────────────
[Show what was created/updated]
[Show key content added]
Status: ✓ Complete
Task 2: [Description]
─────────────────────
[Show what was created/updated]
[Show key content added]
Status: ✓ Complete
[... repeat for each task ...]
───────────────────────────────────────────────
Audit Summary:
- Tasks completed: X/Y
- Files created: [list]
- Files updated: [list]
- Links verified: [X/Y working]
- Remaining items: [list for future]
Documentation audit complete! ✓
All updates look good? (y/n/revise)
Wait for user response before proceeding.
Use when: A feature, fix, or refactoring has been completed and documentation needs updating.
Trigger: "Update documentation for #XXX" / After issue completion
|
Checkpoint 1: Identify Documentation Impacts (WAIT)
|
Checkpoint 2: Update Core Documentation (WAIT)
|
Checkpoint 3: Add Code Documentation (WAIT)
|
Checkpoint 4: Create Usage Examples (WAIT)
|
Documentation Updated
Purpose: Determine what documentation needs updating based on code changes.
Actions:
Output format:
Documentation Update for Issue #XXX
CHECKPOINT 1: Identify Documentation Impacts
───────────────────────────────────────────────
Analyzing changes in issue #XXX...
Code Changes Summary:
- [file 1] ([description of change])
- [file 2] ([description of change])
- [file 3] ([description of change])
Documentation Impacts Identified:
📄 README.md
- [Update/Add]: [specific section and what to change]
📄 docs/architecture/[file].html ← update HTML (primary)
- [Update/Add]: [specific section and what to change]
(also update the companion .md if it exists)
📄 lib/[file].dart (code documentation)
- [Add]: [dartdoc comments needed]
📄 docs/guides/[new-file].html (if needed)
- [Create]: [new HTML guide for this feature]
📄 CLAUDE.md
- [Update]: [if patterns or conventions changed]
Impact Level: [Minor/Moderate/Significant]
Estimated Updates: [X files to update, Y files to create]
Documentation impacts identified? (y/n/add more)
Wait for user response before proceeding.
Purpose: Update README, architecture docs, and main documentation files.
Actions:
Output format:
───────────────────────────────────────────────
CHECKPOINT 2: Update Core Documentation
Updating [file 1]...
[Show specific changes made - before/after or new content added]
✓ [file 1] updated
Updating [file 2]...
[Show specific changes made]
✓ [file 2] updated
[Repeat for each core doc that needs updating]
Summary:
- [X] files updated
- [Y] sections added
- [Z] sections modified
Core documentation updated? (y/n/revise)
Wait for user response before proceeding.
Purpose: Update inline code documentation (dartdoc comments).
Actions:
Output format:
───────────────────────────────────────────────
CHECKPOINT 3: Add Code Documentation
Adding dartdoc to [file 1]...
```dart
/// [Show the dartdoc comments to add]
class MyClass {
/// [Field documentation]
final String field;
/// [Method documentation]
///
/// Example:
/// ```dart
/// [usage example]
/// ```
void method() { ... }
}
✓ [file 1] documented
[Repeat for each file needing code docs]
Code documentation standards applied:
Code docs complete? (y/n/improve)
**Wait for user response before proceeding.**
---
### Checkpoint 4: Create Usage Examples
**Purpose:** Add practical examples and usage guides for the feature.
**Actions:**
1. Create feature guide if significant new feature
2. Add examples showing common usage
3. Document developer notes (how it works internally)
4. Verify all documentation is cross-referenced
**Output format:**
─────────────────────────────────────────────── CHECKPOINT 4: Create Usage Examples
[If creating a new guide:] Creating docs/guides/[feature-name].md...
[Show the guide content]
✓ Usage guide created
[If adding examples to existing docs:] Adding examples to [doc file]...
[Show examples added]
✓ Examples added
Cross-reference check:
───────────────────────────────────────────────
Documentation Update Complete for #XXX! ✓
Summary:
All documentation updated? (y/n/revise)
**Wait for user response before proceeding.**
---
## Process C: Specific Documentation Task
**Use when:** Creating a specific piece of documentation (architecture doc, pattern doc, ADR, etc.).
This process uses **3 checkpoints**: Plan, Draft, Review.
Trigger: "Document the [component]" / "Write an ADR for [decision]" | Checkpoint 1: Plan the Document (WAIT) | Checkpoint 2: Draft the Content (WAIT) | Checkpoint 3: Review and Finalize (WAIT) | Document Complete
### Checkpoint 1: Plan the Document
**Actions:**
1. Determine document type and appropriate template
2. Research the subject (read relevant code and existing docs)
3. Outline the document structure
4. Identify cross-references needed
**Output:** Document outline with sections and key points for user approval.
### Checkpoint 2: Draft the Content
**Actions:**
1. Write complete document using the approved outline
2. Include code examples from actual codebase
3. Add diagrams where helpful (Mermaid)
4. Cross-reference related documentation
**Output:** Complete document draft for user review.
### Checkpoint 3: Review and Finalize
**Actions:**
1. Verify accuracy against code
2. Check all links and references
3. Ensure formatting consistency
4. Save document to appropriate location
**Output:** Final document with verification summary.
---
## Documentation Standards
### README Structure
Every README.md should follow this structure:
```markdown
# Project/Component Name
[Brief description - 1-2 sentences]
## Features
[Bullet list of main features]
## Getting Started
[Quick start instructions]
## Architecture
[High-level overview, link to detailed docs]
## Development
[How to run, test, contribute]
## Documentation
[Links to detailed documentation]
## License
[License information]
/// Brief one-line description.
///
/// Detailed explanation spanning multiple paragraphs if needed.
///
/// Example:
/// ```dart
/// final example = MyClass();
/// example.doSomething();
/// ```
///
/// See also:
/// * [RelatedClass]
/// * [relatedMethod]
class MyClass {
/// Brief description of this field.
final String field;
/// Brief description of this method.
///
/// Explains parameters, behavior, and return value.
///
/// Throws [SomeException] if [condition].
void method(String param) {
// implementation
}
}
Rules:
/// Example: for non-obvious APIs/// See also: for cross-references/// Throws to document exceptionsNew architecture docs are HTML files. Use docs/architecture/Gastrobrain-Codebase-Overview.html as the canonical style reference. Key patterns:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Gastrobrain — [Doc Title]</title>
<style>
/* Self-contained CSS — amber #d97706 primary, green #065f46 accent */
/* Sidebar nav + main content layout */
/* Section cards with color-coded headers per domain */
</style>
</head>
<body>
<div class="layout">
<nav class="sidebar"><!-- jump links --></nav>
<main class="main">
<!-- header block with chips -->
<!-- section-title anchors -->
<!-- domain cards / tables / stat blocks -->
</main>
</div>
</body>
</html>
HTML doc checklist:
<style> is fully self-contained (no <link> to external CSS)<a href="#section-id"> jump links for multi-section docs#d97706 primary, green #065f46 accent, consistent with existing docsid= anchors on every major section for sidebar links<pre><code> blocks for code examples#, ##, ###)See standards/markdown_standards.md for complete conventions.
gastrobrain/
├── README.md (project overview — Markdown)
├── CLAUDE.md (AI assistant instructions — Markdown)
├── docs/
│ ├── architecture/
│ │ ├── Gastrobrain-Codebase-Overview.html ← HTML (primary, human-readable)
│ │ ├── Gastrobrain-Codebase-Overview.md ← Markdown (source / AI-readable)
│ │ ├── gastrobrain-skills-master-index.md ← Markdown (AI-readable)
│ │ └── [new component docs → HTML]
│ ├── archive/
│ │ ├── Gastrobrain-Roadmap-Status.html ← HTML (primary)
│ │ ├── Gastrobrain-Roadmap-Status.md ← Markdown (source)
│ │ └── Sprint-Estimation-Diary.md ← Markdown (working doc)
│ ├── workflows/
│ │ ├── ISSUE_WORKFLOW.md (Markdown — GitHub process doc)
│ │ ├── L10N_PROTOCOL.md (Markdown — GitHub process doc)
│ │ └── [process-specific docs — Markdown]
│ ├── testing/
│ │ ├── DIALOG_TESTING_GUIDE.md (Markdown — referenced in code/GitHub)
│ │ ├── EDGE_CASE_TESTING_GUIDE.md (Markdown)
│ │ ├── EDGE_CASE_CATALOG.md (Markdown)
│ │ └── MOCK_DATABASE_ERROR_SIMULATION.md (Markdown)
│ ├── design/
│ │ └── [design system docs — HTML]
│ ├── guides/
│ │ └── [feature-specific guides — HTML]
│ ├── patterns/
│ │ └── [reusable patterns — HTML]
│ ├── decisions/
│ │ └── [ADRs — HTML]
│ └── planning/
│ └── sprints/
│ └── [sprint plans — Markdown, working docs]
├── lib/
│ └── [dartdoc comments in source]
└── .claude/
└── skills/
└── [skill prompts — Markdown]
PascalCase or kebab-case (follow existing pattern)UPPER_SNAKE_CASE.md (e.g., ISSUE_WORKFLOW.md)kebab-case.md (e.g., getting-started.md)ADR-NNN-kebab-case.md (e.g., ADR-001-meal-type-enum.md)snake_case.md (e.g., feature_guide_template.md)Create an ADR when:
# ADR-NNN: [Decision Title]
Date: YYYY-MM-DD
Status: [Proposed/Accepted/Deprecated/Superseded]
## Context
[What is the issue that we're seeing that motivates this decision?]
## Decision
[What is the change that we're proposing and/or doing?]
## Rationale
[Why did we choose this approach over alternatives?]
## Consequences
**Positive:**
- [Benefit 1]
- [Benefit 2]
**Negative:**
- [Trade-off 1]
- [Trade-off 2]
**Mitigation:**
- [How we handle the negatives]
## Alternatives Considered
### [Alternative 1]
[Description and why rejected]
### [Alternative 2]
[Description and why rejected]
See templates/adr_template.md for the complete template.
Use Mermaid for architecture and flow diagrams in documentation:
Architecture diagrams:
graph TB
UI[Screens & Widgets] --> Provider[State Management]
Provider --> Services[Service Layer]
Services --> Repository[Repository Pattern]
Repository --> Database[(SQLite)]
Sequence diagrams:
sequenceDiagram
User->>Dialog: Interact
Dialog->>Service: Process
Service->>Database: Persist
Database-->>Service: Result
Service-->>Dialog: Update
Entity-Relationship diagrams:
erDiagram
MEAL ||--o{ MEAL_RECIPE : contains
RECIPE ||--o{ MEAL_RECIPE : "used in"
RECIPE ||--o{ RECIPE_INGREDIENT : has
INGREDIENT ||--o{ RECIPE_INGREDIENT : "used in"
See standards/diagram_standards.md for conventions.
Use after every feature/fix before marking issue complete:
Documentation Maintenance Checklist for #XXX
Core Documentation:
- [ ] README.md updated (if feature visible to users)
- [ ] Architecture docs updated (if structure changed)
- [ ] Workflow docs updated (if process changed)
- [ ] CLAUDE.md updated (if conventions changed)
Code Documentation:
- [ ] Public classes have dartdoc comments
- [ ] Public methods have dartdoc comments
- [ ] Complex logic has inline comments
- [ ] Examples provided for non-obvious APIs
Testing Documentation:
- [ ] New test patterns documented (if applicable)
- [ ] Edge cases documented in test comments
Visual Documentation:
- [ ] Diagrams updated (if architecture changed)
Links & References:
- [ ] Internal links working
- [ ] Cross-references accurate
- [ ] New docs linked from parent docs
Templates are provided in templates/ for consistent documentation:
| Template | File | Use When |
|---|---|---|
| Feature Guide | feature_guide_template.md | Documenting a new feature |
| Architecture Doc | architecture_doc_template.md | Documenting a component |
| Pattern Doc | pattern_doc_template.md | Capturing a reusable pattern |
| ADR | adr_template.md | Recording a decision |
| API Doc | api_doc_template.md | Documenting a service/API |
See examples/ directory for full walkthroughs:
example_1_post_implementation.md - Documentation update after feature #XXX
example_2_full_audit.md - Complete documentation audit
example_3_architecture_doc.md - Creating architecture documentation
Before marking documentation task complete, verify:
v1.0.0 (2026-02-07)