documentation-organization

name	documentation-organization
description	Enforces documentation organization standards and provides comprehensive framework documentation authoring for Databricks projects. Operates in two modes: (1) Organizational Enforcement — validates file placement (root directory rules, docs/ hierarchy), naming conventions (kebab-case, date-prefixed), and proactively suggests cleanup for misorganized files. (2) Framework Documentation — orchestrates creation of complete technical documentation sets using fill-in-the-blank templates (index, introduction, architecture, component deep dives, implementation guides, operations guides, troubleshooting guides) with requirements gathering, quality checklists, and worked examples. Use when creating any .md file, organizing existing documentation, maintaining project structure, or creating comprehensive framework documentation sets.
clients	["ide_cli","genie_code"]
bundle_resource	none
deploy_verb	none
deploy_note	Documentation authoring/organization meta-skill — produces `.md` docs; no deployed resource and no deploy verb. Client-agnostic. On Genie Code, write generated docs under the cloned repo root (`{REPO_ROOT}` = `state_file_root` from `skills/vibecoding-state`), not a bare relative path — relative paths resolve against the page CWD (see `skills/genie-code-environment` §8).
coverage	full
metadata	{"author":"prashanth subrahmanyam","version":"2.0.0","domain":"admin","role":"utility","standalone":true,"triggers":["document","checklist","summary","guide","issue","steps","deployment","troubleshooting","framework documentation","documentation set","document this system","create docs","architecture docs","operations guide"],"last_verified":"2026-02-07","volatility":"low","upstream_sources":[]}

Documentation Organization & Framework Authoring

This skill serves two complementary purposes:

1. Organizational Enforcement — Ensures every documentation file lands in the right place with the right name, every time.
2. Framework Documentation Authoring — Orchestrates creation of complete, professional documentation sets for technical frameworks and systems using structured templates.

---

Decision Tree: Which Mode Do I Need?

User Intent	Mode	What Happens
"Create a deployment checklist"	Organizational	Route to docs/deployment/deployment-checklist.md, suggest cleanup
"Document this issue"	Organizational	Route to docs/troubleshooting/issue-YYYY-MM-DD-description.md
"Write next steps"	Organizational	Route to docs/development/roadmap.md or suggest issue tracker
"Document the ML framework"	Framework	Gather requirements, generate full doc set from templates
"Create architecture docs for the alerting system"	Framework	Generate docs/alerting-framework-design/ with all templates
"Help me create comprehensive docs for this project"	Framework	Run full requirements + template workflow
File is .md and being created	Organizational	Auto-check location before creation
Root has >3 .md files	Organizational	Proactively suggest cleanup

---

Mode 1: Organizational Enforcement

Auto-Trigger Conditions

I will automatically enforce organization when:

• Creating any .md file (check location first)
• User mentions: "document", "checklist", "summary", "guide", "issue", "steps"
• Root directory has >3 .md files (excluding README/QUICKSTART/CHANGELOG)
• See files matching patterns: *DEPLOYMENT*, *CHECKLIST*, ISSUE*, *STEPS*, *SUMMARY*

Root Directory Rules (Enforce Always)

ALLOWED in Root (Only These)

README.md              # Project hub with links
QUICKSTART.md          # Commands-only quick start  
CHANGELOG.md           # Version history (optional)
LICENSE                # License file (optional)

NEVER Allowed in Root

*DEPLOYMENT*.md        → docs/deployment/deployment-history/YYYY-MM-DD-name.md
*CHECKLIST*.md         → docs/deployment/checklist-name.md
ISSUE*.md              → docs/troubleshooting/issue-YYYY-MM-DD-description.md
*STEPS*.md             → docs/development/roadmap.md (or delete if temporary)
*SUMMARY*.md           → docs/reference/ or merge into README.md
*GUIDE*.md             → docs/deployment/ or docs/operations/
.hidden-*.md           → docs/[appropriate-category]/

Standard Project Structure (Always Use)

project_root/
├── README.md                          
├── QUICKSTART.md                      
├── docs/
│   ├── deployment/
│   │   ├── deployment-guide.md
│   │   ├── pre-deployment-checklist.md
│   │   ├── deployment-checklist.md
│   │   └── deployment-history/
│   │       └── YYYY-MM-DD-description.md
│   ├── troubleshooting/
│   │   ├── common-issues.md
│   │   └── issue-YYYY-MM-DD-description.md
│   ├── architecture/
│   │   └── architecture-overview.md
│   ├── operations/
│   │   ├── monitoring.md
│   │   └── runbooks/
│   ├── development/
│   │   ├── roadmap.md
│   │   └── setup.md
│   ├── reference/
│   │   ├── configuration.md
│   │   └── glossary.md
│   └── {framework-name}-design/        # Framework documentation sets
│       ├── 00-index.md
│       ├── 01-introduction.md
│       └── ...
└── context/
    └── prompts/

Naming Rules (Always Enforce)

Format	Use For	Example
kebab-case.md	All docs	deployment-guide.md
YYYY-MM-DD-description.md	Historical/dated	2025-01-15-bronze-deployment.md
NN-descriptive-name.md	Framework docs (numbered)	03-feature-engineering.md
NEVER PascalCase.md	--	DeploymentGuide.md
NEVER ALL_CAPS.md	--	DEPLOYMENT_GUIDE.md
NEVER snake_case.md	--	deployment_guide.md

Automatic Response Pattern

Before creating any .md file, I will always check:

# Location routing logic (I run this mentally)
if filename in ["README.md", "QUICKSTART.md", "CHANGELOG.md"]:
    location = "root"  # OK
elif "deployment" in content or "checklist" in filename:
    location = "docs/deployment/"
elif "issue" in filename or "troubleshoot" in content:
    location = "docs/troubleshooting/"
elif "architecture" in content or "design" in content:
    location = "docs/architecture/"
elif user_intent == "framework documentation":
    location = "docs/{framework-name}-design/"  # → Switch to Mode 2
elif user_intent == "temporary notes":
    suggest_alternative = "Use issue tracker or delete after completion"

My response format:

I'll create that documentation in the correct location:
  docs/[category]/[kebab-case-name].md

I also notice these files should be organized:
  DEPLOYMENT_COMPLETE.md → docs/deployment/deployment-history/2025-01-15-summary.md
  .deployment-checklist.md → docs/deployment/deployment-checklist.md
  ISSUE_RESOLUTION.md → docs/troubleshooting/issue-2025-01-15-parameter-fix.md

Would you like me to reorganize these?

Proactive Cleanup Suggestions

Trigger: User Creates Documentation

User Says	I Suggest
"Create a deployment summary"	docs/deployment/deployment-history/YYYY-MM-DD-summary.md
"Document this issue"	docs/troubleshooting/issue-YYYY-MM-DD-brief-description.md
"Make a checklist"	docs/deployment/[type]-checklist.md
"Write next steps"	docs/development/roadmap.md or "Use issue tracker instead?"

Trigger: Multiple Files in Root

When I see >3 .md files in root:

Root directory has [N] documentation files. I recommend organizing them:

Current structure:
  7 files in root

Suggested structure:
  3 files in root (README, QUICKSTART, CHANGELOG)
  4 files in docs/deployment/
  
Would you like me to create a cleanup plan?

See scripts/organize_docs.sh for the automated cleanup script.

Special Cases

Temporary Files

If user wants "quick notes" or "temporary file":

• Suggest: Use your IDE scratch file or issue tracker
• Alternative: docs/development/wip-notes.md (but add reminder to delete)

Historical Records

Always preserve, never delete:

• docs/deployment/deployment-history/YYYY-MM-DD-description.md
• docs/troubleshooting/issue-YYYY-MM-DD-description.md

Consolidation Opportunity

If I see duplicate content:

I notice:
- README.md has deployment info (100 lines)
- docs/deployment/deployment-guide.md has same content
- QUICKSTART.md duplicates some steps

Suggest:
- Keep brief summary in README with link
- Full guide in docs/deployment/deployment-guide.md
- QUICKSTART only has commands, links to guide for details

---

Mode 2: Framework Documentation Authoring

Use this mode when creating comprehensive documentation for a technical framework, system, or multi-component project. This is an orchestrated workflow that produces a complete, professional documentation set.

When to Activate Framework Mode

• User asks to "document the [framework/system]"
• User asks for "architecture docs", "comprehensive docs", or "documentation set"
• Project has 5+ components that need structured documentation
• User is creating documentation for training or onboarding purposes

Step 1: Requirements Gathering (5 min)

MANDATORY: Before generating any templates, gather requirements from the user.

Present the requirements table (see references/framework-examples.md for the full template):

Field	Your Input
Framework/System Name	_________________
Primary Audience	_________________
Secondary Audience	_________________
Documentation Purpose	[ ] Project Documentation [ ] Training Material [ ] Both
Technology Stack	_________________
Number of Components	_________________

Then determine documentation depth:

Level	Description	Needed?
Executive Summary	1-page overview for leadership	[ ]
Architecture Guide	System design, data flows, component interactions	[ ]
Implementation Guide	Step-by-step build instructions	[ ]
Operations Guide	Deployment, monitoring, maintenance	[ ]
Reference Manual	API docs, configurations, schemas	[ ]
Troubleshooting Guide	Common errors and solutions	[ ]
Best Practices	Patterns and anti-patterns	[ ]

Step 2: Generate File Structure (5 min)

Based on requirements, create the numbered file structure under docs/{framework-name}-design/:

docs/{framework-name}-design/
├── 00-index.md                    # Always included
├── 01-introduction.md             # Always included
├── 02-architecture-overview.md    # If Architecture Guide selected
├── 03-{component-type-1}.md       # Per major component
├── 04-{component-type-2}.md       # Per major component
├── ...
├── {n}-implementation-guide.md    # If Implementation Guide selected
├── {n+1}-operations-guide.md      # If Operations Guide selected
└── appendices/
    ├── A-code-examples.md         # If Reference Manual selected
    ├── B-troubleshooting.md       # If Troubleshooting Guide selected
    └── C-references.md            # Always included

Step 3: Fill Templates (Varies — 30 min to 4 hours)

Load references/document-templates.md for complete fill-in-the-blank templates.

Templates available (load only the ones needed):

1. 00-index.md — Document index, architecture summary, quick start, key statistics
2. 01-introduction.md — Purpose, scope, prerequisites, timeline, success criteria
3. 02-architecture-overview.md — Mermaid/ASCII diagrams, data flows, component inventory, design principles
4. Component Deep Dive — Key concepts, configuration, code patterns, best practices, common issues
5. Implementation Guide — Phased steps with validation, deployment commands, rollback procedures
6. Operations Guide — Health checks, alerting, escalation matrix, incident response, backup/recovery
7. Troubleshooting Guide — Error-solution matrix, diagnostic procedures, FAQ

Step 4: Quality Validation

Load references/quality-checklist.md for the comprehensive quality checklist covering:

1. Organization & Location (7 checks)
2. Naming Conventions (5 checks)
3. Structure & Navigation (6 checks)
4. Content Quality (7 checks)
5. Usability (6 checks)
6. Maintenance & Longevity (5 checks)
7. Special Cases (7 checks)

Worked Examples

Load references/framework-examples.md for complete worked examples including:

• ML Framework (25 models, 5 domains → 17 docs + 3 appendices)
• Alerting Framework (56 alerts, 5 domains → 10 docs + 3 appendices)
• Semantic Layer (focused scope → 7 docs + 3 appendices)
• Scaling guidelines (small/medium/large projects)

---

Enforcement Checklist (I Run Mentally Before Every Response)

Before responding to any documentation request:

• Location: Is this README/QUICKSTART/CHANGELOG? (only valid root files)
• Routing: Propose correct docs/[category]/ location
• Naming: Use kebab-case, add date if historical, add number if framework doc
• Root audit: Count root .md files — suggest cleanup if >3
• Misplaced files: Offer to move existing misplaced files
• README links: Update README.md links if creating major new documentation
• Mode detection: Is this organizational (quick routing) or framework (full template workflow)?

---

Examples

Example 1: Organizational Mode (Quick Routing)

User: "Create a deployment checklist"

My response:
I'll create: docs/deployment/deployment-checklist.md

I also see these in root that should be moved:
- DEPLOYMENT_COMPLETE.md → docs/deployment/deployment-history/2025-01-15-summary.md
- PRE_DEPLOYMENT_CHECKLIST.md → docs/deployment/pre-deployment-checklist.md

Want me to reorganize?

Example 2: Organizational Mode (Bad — I Never Do This)

User: "Create a deployment checklist"

My response:
I'll create: DEPLOYMENT_CHECKLIST.md   [WRONG — wrong location, wrong naming]
[Creates file without checking structure]  [WRONG — no proactive cleanup]

Example 3: Framework Mode (Full Workflow)

User: "Document the ML framework"

My response:
I'll create comprehensive framework documentation. First, let me gather requirements:

1. Framework Name: ML Framework
2. Primary Audience: ML Engineers
3. Components: 25 models across 5 domains
4. Depth needed: Architecture + Implementation + Operations + Troubleshooting