Create a comprehensive project documentation suite from scratch by analyzing the codebase and verifying every claim against it. Use when setting up INITIAL documentation for a project or building a complete docs/ suite where none exists. NOT for updating existing docs (use documentation-sync instead). Covers project analysis, documentation structure, templates, and verification.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Create a comprehensive project documentation suite from scratch by analyzing the codebase and verifying every claim against it. Use when setting up INITIAL documentation for a project or building a complete docs/ suite where none exists. NOT for updating existing docs (use documentation-sync instead). Covers project analysis, documentation structure, templates, and verification.
Documentation Creation Skill
Profile keys consumed
project.name
project.repo
php.version
framework.name
framework.version
framework.api_platform
framework.graphql
persistence.mapper
persistence.engine
architecture.source_root
architecture.bounded_contexts
architecture.shared_context
make.ci
make.start
make.tests
make.e2e
make.load_tests
quality.phpinsights.complexity
quality.infection_msi
capabilities.load_testing
Overview
This skill guides the creation of comprehensive project documentation
from scratch by analyzing the project codebase against the project
profile and applying consistent documentation patterns. It ensures
documentation accurately reflects the actual project implementation.
Use this skill for: initial documentation creation from scratch
: updating existing documentation when
code changes
Use documentation-sync for
Context (Input)
Need to create documentation for a project from scratch
Want consistent style across the whole documentation suite
Need to ensure documentation accuracy against the actual codebase
Project has no existing comprehensive documentation
Task (Function)
Create comprehensive, accurate project documentation by:
Analyzing the project codebase thoroughly, starting from the profile
Creating documentation using the established templates
Verifying all references against the actual codebase
Ensuring consistent style and cross-linking
Success criteria:
All documentation files created with consistent structure
All code references verified against the actual project structure
All directory paths and file mentions exist in the codebase
All links between documentation files work correctly
Technology stack accurately reflected (no false claims)
Quick Start: Documentation Creation Workflow
Step 1: Analyze Project Structure
The profile declares what the project claims to be; the codebase shows
what it is. Read the profile first, then verify each claim. In the
commands below, $SRC is architecture.source_root and $CTX iterates
architecture.bounded_contexts plus architecture.shared_context
(when not null).
# Check project structurels -la "$SRC"/
# Identify technology stackcat composer.json | grep -A5 "require"cat Dockerfile
cat docker-compose.yml
# Verify each declared bounded context existsfor CTX in <each architecture.bounded_contexts entry, plus architecture.shared_context>; dols -la "$SRC/$CTX/" 2>/dev/null || echo"Profile drift: $SRC/$CTX missing"done# Check for entities
find "$SRC" -path "*/Entity/*.php"# Check for commands and handlers (CQRS surface)
find "$SRC" -name "*Command.php" | head -20
find "$SRC" -name "*Handler.php" | head -20
Bounded contexts (architecture.bounded_contexts) and their purposes,
plus the shared kernel (architecture.shared_context) when present
Main entities and their relationships
Available make targets (from the profile make map) and testing tools
Step 2: Create Technology Stack Summary
Verify the profile's stack claims against the repository before
documenting them:
# PHP version — must match php.version
grep -i "php:" Dockerfile
grep '"php"' composer.json
# Framework — must match framework.name / framework.version
grep -i "<framework.name>" composer.json
# Database — must match persistence.engine
grep -iE "mysql|mariadb|postgres|mongo" docker-compose.yml
# Available make targets — the names the make.* map points at
grep -E "^[a-zA-Z][a-zA-Z0-9_-]*:" Makefile | head -30
Create a technology summary table sourced from the verified profile
values:
Component
Technology
Version
Language
PHP
php.version
Runtime
{from Dockerfile}
-
Framework
framework.name
framework.version
Database
persistence.engine
{from docker-compose}
Mapper
persistence.mapper
-
Web Server
{from docker-compose}
-
Step 3: Create Documentation Files
Create each documentation file following this order:
main.md - Project overview and design principles
getting-started.md - Installation and quick start
design-and-architecture.md - Architectural decisions and patterns
developer-guide.md - Code structure and development workflow
api-endpoints.md - REST API documentation; include a GraphQL
section only when framework.graphql is true, and API Platform
specifics only when framework.api_platform is a version string
testing.md - Testing strategy and commands
glossary.md - Domain terminology and naming conventions
user-guide.md - API usage examples
advanced-configuration.md - Environment and configuration
performance.md - Benchmarks and optimization; cover load testing
only when capabilities.load_testing is true, documenting the
Makefile target mapped by make.load_tests
security.md - Security measures and practices
operational.md - Operational considerations
onboarding.md - New contributor guide
community-and-support.md - Support channels
legal-and-licensing.md - License and dependencies
release-notes.md - Release process
versioning.md - Versioning policy
Add project-specific docs as needed (e.g. a runtime-specific
performance page when the project uses a non-standard PHP runtime)
Step 4: Write Each Documentation File
For each documentation file:
Use the appropriate template (see Documentation Templates below)
Fill in project-specific content:
Project name: use project.name consistently throughout
Repository links: build from project.repo
(https://github.com/<project.repo>)
Entity names from the codebase
Bounded context names from architecture.bounded_contexts
Verify all references:
Directory paths exist under architecture.source_root
Every documented make invocation uses the actual target name the
profile make map points at (e.g. the target mapped by make.ci)
and that target exists in the Makefile. A null mapping means the
capability is absent: do not document it; note the gap instead
Entity names match the codebase
Add cross-links to related documentation
Quality thresholds: where testing.md or performance.md cite
quality bars, take values only from the profile quality.* keys —
canonical defaults are complexity 94 (quality.phpinsights.complexity)
and MSI 100 (quality.infection_msi). Thresholds are raise-only:
never document a bar lower than the shipped default
Step 5: Verify Accuracy
Run comprehensive verification (full checklist below):
# Getting Started## Prerequisites
{List required software with versions}
## Installation
{Step-by-step installation commands; boot the service via the target
mapped by make.start}
## Verification
{Commands to verify installation}
Derive the remaining files from the structure in Format (Output) below,
keeping headings and tone consistent with these two templates.
Constraints
NEVER
Include references to non-existent directories or files
Claim features or technologies the project doesn't use (e.g. a GraphQL
page when framework.graphql is false)
Leave placeholder text unreplaced
Skip the verification step after creating documentation
Document make targets that don't exist in the Makefile, or logical
profile key names (make.ci) as if they were target names — always
document the mapped target
Document quality thresholds below the profile quality.* values
ALWAYS
Verify every directory path mentioned exists
Confirm the technology stack matches both the profile and the repo
Test command examples work in the project
Update all cross-references to point to correct files
Maintain consistent terminology throughout; project.name is the only
name used for the project
Add a Table of Contents to longer documents (100+ lines)
Verification Checklist
After creating documentation:
Technology Accuracy
PHP version matches Dockerfile and php.version
Framework version matches composer.json and framework.version
Database type matches docker-compose.yml and persistence.engine
Mapper (ORM vs ODM) described per persistence.mapper
Runtime environment correctly described
No false claims about unused technologies
Structure Accuracy
All mentioned source directories exist under
architecture.source_root
All bounded context names match architecture.bounded_contexts
(and architecture.shared_context)
Entity names match the actual codebase
Command and handler names are accurate
Command Accuracy
All documented make targets exist in the Makefile and come from
the profile make map; null capabilities are noted, not documented
Docker commands work as documented
Test commands (targets mapped by make.tests, make.e2e) produce
the documented output
Link Accuracy
All internal markdown links resolve
External repository links match project.repo
No broken navigation links
Content Consistency
Project name (project.name) consistent throughout
Terminology consistent across documents
No placeholder text remaining
Common Pitfalls
Technology Mismatch
Problem: Documenting technologies the project doesn't use
Solution:
# Verify before documenting
grep -i "fpm\|franken" Dockerfile
cat docker-compose.yml
# Only document what actually exists — and reconcile with the profile
Missing Directories
Problem: Documenting directories that don't exist under the source
root
Solution:
# Verify before documentingls -la "$SRC"/
# Update to match the actual structure
Outdated Commands
Problem: Documenting non-existent make targets, or writing logical
key names instead of the mapped targets
Solution:
# Check the actual Makefile against the profile make map
grep -E "^[a-zA-Z][a-zA-Z0-9_-]*:" Makefile
