levnikolaevich/ln-113-backend-docs-creator

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

Backend Documentation Creator

Type: L3 Worker

L3 Worker that creates 2 backend documentation files. CONDITIONAL - only invoked when project has backend or database.

Purpose & Scope

• Creates api_spec.md (if hasBackend)
• Creates database_schema.md (if hasDatabase)
• Receives Context Store from ln-110-project-docs-coordinator
• OpenAPI 3.0 compliant API specification
• ER diagrams in Mermaid for database schema
• Never gathers context itself; uses coordinator input

Invocation (who/when)

• ln-110-project-docs-coordinator: CONDITIONALLY invoked when:
  • hasBackend=true (express, fastify, nestjs, fastapi detected)
  • hasDatabase=true (pg, mongoose, prisma, sequelize detected)
• Never called directly by users

Inputs

From coordinator:

• contextStore: Context Store with backend-specific data
  • API_TYPE (REST, GraphQL, gRPC)
  • API_ENDPOINTS (from route scan)
  • AUTH_SCHEME (JWT, OAuth2, API keys)
  • DATABASE_TYPE (PostgreSQL, MongoDB, MySQL)
  • SCHEMA_OVERVIEW (from migrations/models)
  • ER_DIAGRAM (generated from schema)
• targetDir: Project root directory
• flags: { hasBackend, hasDatabase }

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, conditional)

| File | Condition | Questions | Auto-Discovery | |------|-----------|-----------|----------------| | docs/project/api_spec.md | hasBackend | Q39-Q40 | Medium | | docs/project/database_schema.md | hasDatabase | Q41-Q42 | High |

Workflow

Phase 1: Check Conditions

1. Parse flags from coordinator
2. If !hasBackend && !hasDatabase: return early with empty result
3. Determine which documents to create

Phase 2: Create Documents

For each applicable document:

1. Check if file exists (idempotent)
2. If exists: skip with log
3. If not exists:
   • Copy template
   • Replace placeholders with Context Store values
   • Preserve the shared opening contract and standard top sections from the template
   • Generate ER diagram for database_schema.md
   • Never leave template markers in published backend docs
   • If data is missing: omit the claim or use a concise neutral fallback, but do NOT emit [TBD: ...]

Phase 3: Self-Validate

1. Check SCOPE tag and metadata markers
2. Check required top sections (Quick Navigation, Agent Entry, Maintenance)
3. Validate format:
   • api_spec.md: endpoint table, request/response examples
   • database_schema.md: ER diagram, table definitions
4. Check docs-quality contract compliance (no forbidden placeholders, no leaked template metadata, valid doc kind/role)

Phase 4: Return Status

{
  "created_files": ["docs/project/api_spec.md"],
  "skipped_files": ["docs/project/database_schema.md"],
  "quality_inputs": {
    "doc_paths": ["docs/project/api_spec.md", "docs/project/database_schema.md"],
    "owners": {
      "docs/project/api_spec.md": "ln-113-backend-docs-creator",
      "docs/project/database_schema.md": "ln-113-backend-docs-creator"
    }
  },
  "validation_status": "passed"
}

Critical Notes

• Conditional: Skip entirely if no backend/database detected
• OpenAPI compliant: api_spec.md follows OpenAPI 3.0 structure
• ER diagrams: Generated in Mermaid erDiagram format
• Idempotent: Never overwrite existing files
• Publishable output: No [TBD: ...], TODO, or leaked template metadata in backend docs

NO_CODE_EXAMPLES Rule (MANDATORY)

API spec documents contracts, NOT implementations:

• ALLOWED in api_spec.md: JSON request/response schemas (this IS the API contract), endpoint tables
• FORBIDDEN: Controller implementations, validation classes, service code, middleware examples
• TEMPLATE RULE: api_spec_template.md includes <!-- NO_CODE_EXAMPLES: ... --> tag - FOLLOW IT

Stack Adaptation Rule (MANDATORY)

• Links must reference stack-appropriate docs (Microsoft for .NET, MDN for JS)
• API examples must match project stack (Express for Node.js, FastAPI for Python)

Format Priority (MANDATORY)

Tables (endpoints, schemas) > Mermaid (ER diagrams) > Lists > 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-113"
• 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

• [ ] Conditions checked (hasBackend, hasDatabase)
• [ ] Applicable documents created
• [ ] ER diagram generated (if database_schema.md created)
• [ ] Self-validation passed (metadata markers, top sections, format)
• [ ] Actuality verified: all document facts match current code (paths, functions, APIs, configs exist and are accurate)
• [ ] Status returned

Reference Files

• Templates: references/templates/api_spec_template.md, references/templates/database_schema_template.md
• Questions: references/questions_backend.md (Q39-Q42)

---

Version: 1.2.0 Last Updated: 2025-01-12