ln-115-devops-docs-creator

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

DevOps Documentation Creator

Type: L3 Worker

L3 Worker that creates infrastructure.md and runbook.md. Infrastructure inventory is always created; runbook is conditional on Docker presence.

Purpose & Scope

• Creates infrastructure.md (always) — declarative inventory: WHAT is deployed WHERE
• Creates runbook.md (if hasDocker) — procedural guide: HOW to deploy/restart/troubleshoot
• Receives Context Store from ln-110-project-docs-coordinator
• Never gathers context itself; uses coordinator input

Invocation (who/when)

• ln-110-project-docs-coordinator: ALWAYS invoked (infrastructure.md is unconditional)
• Never called directly by users

Inputs

From coordinator:

• contextStore: Context Store with DevOps-specific data
• DOCKER_COMPOSE_DEV (development setup)
• DOCKER_COMPOSE_PROD (production setup)
• ENV_VARIABLES (from .env.example)
• STARTUP_SEQUENCE (services order)
• DEPLOYMENT_TARGET (AWS, Vercel, Heroku)
• CI_CD_PIPELINE (from .github/workflows)
• DOCKER_SERVICES (parsed from docker-compose.yml services)
• DEPLOYMENT_SCALE ("single" | "multi" | "auto-scaling" | "gpu-based")
• DEVOPS_CONTACTS (from CODEOWNERS, package.json author, git log)
• HAS_GPU (detected from docker-compose nvidia runtime)
• SERVER_INVENTORY (from SSH config, deploy targets)
• DOMAIN_DNS (from docker-compose VIRTUAL_HOST vars, nginx configs)
• ARTIFACT_REPOSITORY (from .env registry URLs, .npmrc, pip.conf)
• HOST_REQUIREMENTS (from docker-compose deploy.resources.limits)
• targetDir: Project root directory
• flags: { hasDocker }

MANDATORY READ: Load references/docs_quality_contract.md, and references/markdown_read_protocol.md. Optional rule catalog: load references/docs_quality_rules.json only when exact rule IDs, path matrices, or allowlisted placeholder exceptions are needed.

Documents Created (2: 1 always + 1 conditional)

| File | Condition | Questions | Auto-Discovery | |------|-----------|-----------|----------------| | docs/project/infrastructure.md | Always | Q52-Q55 | Medium | | docs/project/runbook.md | hasDocker | Q46-Q51 | High |

Workflow

Phase 1: Check Conditions

1. Parse flags from coordinator
2. infrastructure.md: ALWAYS proceeds (no condition check)
3. runbook.md: Create ONLY if hasDocker=true
4. If target file already exists: skip that file (idempotent)

Phase 2a: Create infrastructure.md (unconditional)

1. Check if docs/project/infrastructure.md exists
2. If exists: skip with log
3. If not exists:
4. Copy references/templates/infrastructure_template.md
5. Replace placeholders with Context Store values
6. Preserve the shared opening contract and standard top sections from the template
7. Populate Server Inventory from SERVER_INVENTORY
8. Populate Port Allocation from DOCKER_SERVICES port mappings
9. Populate Deployed Services from DOCKER_SERVICES
10. Populate CI/CD Pipeline from CI_CD_PIPELINE
11. Never leave template markers in published infrastructure docs
12. If data is missing: omit the claim or use a concise neutral fallback, but do NOT emit [TBD: ...]
13. Conditional Section Pruning:
14. If no CI/CD detected: replace with concise empty-state note, not [TBD: ...]
15. If no ARTIFACT_REPOSITORY: replace with concise empty-state note, not [TBD: ...]
16. If single server / no SERVER_INVENTORY: simplify to single-column table
17. If !HAS_GPU: remove GPU column from Server Inventory and Deployed Services
18. Populate Deployed Services ONLY from DOCKER_SERVICES (no generic examples)

Phase 2b: Create runbook.md (conditional)

1. If !hasDocker: skip entirely
2. Check if docs/project/runbook.md exists
3. If exists: skip with log
4. If not exists:
5. Copy references/templates/runbook_template.md
6. Replace placeholders with Context Store values
7. Preserve the shared opening contract and standard top sections from the template
8. Populate setup steps from package.json scripts
9. Extract env vars from .env.example
10. Never leave template markers in published runbooks
11. If data is missing: omit the claim or use a concise neutral fallback, but do NOT emit [TBD: ...]
12. Conditional Section Pruning:
13. If DEPLOYMENT_SCALE != "multi" or "auto-scaling": Remove scaling/load balancer sections
14. If !HAS_GPU: Remove GPU-related sections (nvidia runtime, CUDA)
15. If service not in DOCKER_SERVICES: Remove that service's examples
16. If DEVOPS_CONTACTS empty: replace with concise empty-state note, not [TBD: ...]
17. Populate service dependencies ONLY from DOCKER_SERVICES
18. Populate port mapping ONLY from docker-compose.yml ports section

Phase 3: Self-Validate

For infrastructure.md:

1. Check SCOPE tag and metadata markers
2. Check required top sections (Quick Navigation, Agent Entry, Maintenance)
3. Validate sections: Server Inventory, Port Allocation, Deployed Services
4. Check no procedural content leaked (belongs in runbook.md)
5. Check docs-quality contract compliance (no forbidden placeholders, no leaked template metadata, valid doc kind/role)

For runbook.md (if created):

1. Check SCOPE tag and metadata markers
2. Check required top sections (Quick Navigation, Agent Entry, Maintenance)
3. Validate sections: Local Development Setup, Deployment, Troubleshooting
4. Check env vars documented
5. Check docs-quality contract compliance (no forbidden placeholders, no leaked template metadata, valid doc kind/role)

Phase 4: Return Status

{
  "created_files": ["docs/project/infrastructure.md", "docs/project/runbook.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/project/infrastructure.md", "docs/project/runbook.md"],
    "owners": {
      "docs/project/infrastructure.md": "ln-115-devops-docs-creator",
      "docs/project/runbook.md": "ln-115-devops-docs-creator"
    }
  },
  "validation_status": "passed"
}

Critical Notes

Core Rules

• infrastructure.md: Always created, no condition
• runbook.md: Conditional on hasDocker
• Heavy auto-discovery: Most data from docker-compose.yml, .env.example, package.json, SSH config
• Reproducible: Setup steps must be testable and repeatable
• Idempotent: Never overwrite existing files
• Publishable output: No [TBD: ...], TODO, or leaked template metadata in DevOps docs

NO_CODE_EXAMPLES Rule (MANDATORY)

Both documents describe inventory/procedures, NOT implementations:

• FORBIDDEN: Full Docker configs, CI/CD pipelines (>5 lines), full nginx configs
• ALLOWED: Command examples (1-3 lines), env var tables, step lists, verification commands
• INSTEAD OF CODE: "See [docker-compose.yml](../docker-compose.yml)"

Stack Adaptation Rule (MANDATORY)

• Commands must match project stack (npm vs pip vs go)
• Link to correct cloud provider docs (AWS/Azure/GCP)
• Never mix stack references (no npm commands in Python project)

Format Priority (MANDATORY)

Tables (env vars, ports, services, servers) > Lists (setup steps) > Text

Runtime Summary Artifact

MANDATORY READ: Load references/docs_generation_summary_contract.md

Accept optional summaryArtifactPath.

Summary kind:

• docs-generation

Required payload semantics:

• worker = "ln-115"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

Write the summary to the provided artifact path or return the same envelope in structured output.

Definition of Done

• [ ] infrastructure.md created (always)
• [ ] runbook.md created if hasDocker
• [ ] Infrastructure: server inventory, ports, services documented
• [ ] Runbook: setup steps, deployment, troubleshooting documented
• [ ] All env vars from .env.example included in runbook
• [ ] Actuality verified: all document facts match current code (paths, functions, APIs, configs exist and are accurate)
• [ ] Status returned

Refe