shift-left-docset-generator

id: SKL-shiftleft-SHIFTLEFTDOCSETGENERATOR name: Shift-Left Docset Generator description: Generate a standardized shift-left engineering documentation set (Blueprint, Requirements, Verification, Architecture, Contract, Specs, Operation, and Agentic Work Ticket) under a target project docs folder using canonical 1:1 heading templates. version: 1.0.0 status: active owner: '@cerebra-team' last_updated: '2026-02-23' category: Backend tags:

• documentation
• shift-left
• scaffolding
• engineering-process stack:
• Markdown
• Documentation-as-Code
• CI/CD difficulty: Intermediate

Shift-Left Docset Generator

Skill Profile

(Select at least one profile to enable specific modules)

• DevOps
• Backend
• Frontend
• AI-RAG
• Security Critical

Overview

Generate a complete shift-left documentation set in one pass so teams can align from business intent to implementation and operations early in the lifecycle. This skill scaffolds a fixed folder and file structure using canonical templates with 1:1 heading parity to the B3F reference docs.

Why This Matters

• Early risk reduction: Identify requirement, architecture, and contract issues before coding starts
• Cross-team alignment: Product, engineering, QA, and operations share the same baseline artifacts
• Faster delivery: Reusable templates remove repeated setup work for every new initiative
• Auditability: Decisions, assumptions, and verification evidence are traceable from day one

Core Concepts & Rules

1. Shift-Left Principles

• Start with intent and constraints before implementation
• Define testability and verification criteria with requirements
• Lock integration contracts before service coding
• Treat documentation as a first-class deliverable

2. File System Contract

• Always create exactly these directories and files under <project_root>/docs:
  • 00-Blueprint/blueprint.md
  • 01-Requirements/requirements.md
  • 02-Verification/verification.md
  • 03-Architecture/architecture.md
  • 04-Contract/contract.md
  • 05-Specs/specs.md
  • 06-Operation/operation.md
  • 07-Agentic_work_ticket/ticket_template.md
• Do not rename folder numbers or filenames unless explicitly requested
• Prefer idempotent generation (create-if-missing, preserve-existing-by-default)

3. Template Standard (Must Use)

• Use canonical templates from:
  • templates/shift-left-docset/00-Blueprint/blueprint.md
  • templates/shift-left-docset/01-Requirements/requirements.md
  • templates/shift-left-docset/02-Verification/verification.md
  • templates/shift-left-docset/03-Architecture/architecture.md
  • templates/shift-left-docset/04-Contract/contract.md
  • templates/shift-left-docset/05-Specs/specs.md
  • templates/shift-left-docset/06-Operation/operation.md
  • templates/shift-left-docset/07-Agentic_work_ticket/ticket_template.md
• Heading structure in generated files must match template headings 1:1.
• Allowed customization: project-specific body content under existing headings.
• Not allowed: adding/removing/renaming required headings without explicit override.

Inputs / Outputs / Contracts

• Inputs:
  • Target project root path (example: D:\B3F_Intelligence_Engine)
  • Project context: problem statement, scope, constraints, stakeholders
  • Non-functional requirements: performance, security, reliability, compliance
• Entry Conditions:
  • Write access to target project directory
  • docs folder exists or can be created
• Outputs:
  • Complete 8-file shift-left docset scaffold
  • Starter content in each markdown file with canonical headings
• Artifacts Required (Deliverables):
  • docs/00-Blueprint/blueprint.md
  • docs/01-Requirements/requirements.md
  • docs/02-Verification/verification.md
  • docs/03-Architecture/architecture.md
  • docs/04-Contract/contract.md
  • docs/05-Specs/specs.md
  • docs/06-Operation/operation.md
  • docs/07-Agentic_work_ticket/ticket_template.md
• Acceptance Evidence:
  • All required files exist at the exact paths
  • Each generated file has heading parity 1:1 with template
  • Each file has non-empty core sections
  • Links and references across docs resolve correctly
• Success Criteria:
  • Structure compliance: 100%
  • Heading parity with template: 100%
  • Required section completeness: 100%
  • Generation is repeatable without corruption of existing content

Skill Composition

• Depends on: technical-writing, requirement-analysis
• Compatible with: runbooks, definition-of-done
• Conflicts with: None
• Related Skills: service-scaffold-generator, ci-pipeline-generator

Quick Start / Implementation Example

1. Set PROJECT_ROOT to target path.
2. Create all 8 directories and markdown files with fixed names.
3. Copy canonical template content into each target file (1:1 headings).
4. Fill project-specific content under each heading.
5. Cross-link related docs (requirements -> verification -> specs).
6. Validate file existence, heading parity, and section completeness.
7. Commit scaffold as baseline before feature coding.

PROJECT_ROOT="D:/B3F_Intelligence_Engine"
DOCS_ROOT="$PROJECT_ROOT/docs"

mkdir -p \
  "$DOCS_ROOT/00-Blueprint" \
  "$DOCS_ROOT/01-Requirements" \
  "$DOCS_ROOT/02-Verification" \
  "$DOCS_ROOT/03-Architecture" \
  "$DOCS_ROOT/04-Contract" \
  "$DOCS_ROOT/05-Specs" \
  "$DOCS_ROOT/06-Operation" \
  "$DOCS_ROOT/07-Agentic_work_ticket"

touch \
  "$DOCS_ROOT/00-Blueprint/blueprint.md" \
  "$DOCS_ROOT/01-Requirements/requirements.md" \
  "$DOCS_ROOT/02-Verification/verification.md" \
  "$DOCS_ROOT/03-Architecture/architecture.md" \
  "$DOCS_ROOT/04-Contract/contract.md" \
  "$DOCS_ROOT/05-Specs/specs.md" \
  "$DOCS_ROOT/06-Operation/operation.md" \
  "$DOCS_ROOT/07-Agentic_work_ticket/ticket_template.md"

# Copy canonical templates (run from CerebraSkills repo root)
cp -f "templates/shift-left-docset/00-Blueprint/blueprint.md" "$DOCS_ROOT/00-Blueprint/blueprint.md"
cp -f "templates/shift-left-docset/01-Requirements/requirements.md" "$DOCS_ROOT/01-Requirements/requirements.md"
cp -f "templates/shift-left-docset/02-Verification/verification.md" "$DOCS_ROOT/02-Verification/verification.md"
cp -f "templates/shift-left-docset/03-Architecture/architecture.md" "$DOCS_ROOT/03-Architecture/architecture.md"
cp -f "templates/shift-left-docset/04-Contract/contract.md" "$DOCS_ROOT/04-Contract/contract.md"
cp -f "templates/shift-left-docset/05-Specs/specs.md" "$DOCS_ROOT/05-Specs/specs.md"
cp -f "templates/shift-left-docset/06-Operation/operation.md" "$DOCS_ROOT/06-Operation/operation.md"
cp -f "templates/shift-left-docset/07-Agentic_work_ticket/ticket_template.md" "$DOCS_ROOT/07-Agentic_work_ticket/ticket_template.md"

Assumptions / Constraints / Non-goals

• Assumptions:
  • Team agrees to documentation-first workflow
  • Markdown is accepted as project documentation format
• Constraints:
  • Keep naming and numbering stable for automation and discoverability
  • Preserve existing file content unless overwrite is explicitly requested
• Non-goals:
  • Does not auto-generate final business content from thin input
  • Does not replace architecture review or security review processes

Compatibility & Prerequisites

• Supported Versions:
  • Any OS with standard filesystem support
  • Git-based repository workflow
• Required AI Tools:
  • File read/write tool access
  • Terminal for directory/file scaffolding
• Dependencies:
  • Markdown linter (optional)
  • CI doc checks (optional)
• Environment Setup:
  • .env.example keys: PROJECT_ROOT, DOCS_ROOT (no values)

Test Scenario Matrix (QA Strategy)

Technical Guardrails & Security Threat Model

1. Security & Privacy (Threat Model)

• Top Threats: Path traversal, accidental overwrite, disclosure of sensitive design details

• Data Handling: Redact secrets, credentials, and raw PII from docs
• Secrets Management: Never write secrets to markdown templates
• Authorization: Restrict generation to approved project directories

2. Performance & Resources

• Execution Efficiency: Use batch directory creation and minimal file operations
• Memory Management: Stream large template writes if needed
• Resource Cleanup: Remove temp files created during generation/validation

3. Architecture & Scalability

• Design Pattern: Use deterministic scaffolding logic and schema-validated templates
• Modularity: Separate path resolution, file generation, and content templating

4. Observability & Reliability

• Logging Standards: Log created/updated/skipped files with timestamps and request_id
• Metrics: Track generation_duration_ms, files_created, files_skipped, errors
• Error Handling: Stop on path contract violations and report exact failure
• Observability Artifacts:
  • Log Fields: timestamp, level, action, path, request_id
  • Metrics: generation_duration_ms, files_created, files_skipped, generation_error_count
  • Dashboards/Alerts: Alert when generation_error_count > 0

Agent Directives & Error Recovery

(ข้อกำหนดสำหรับ AI Agent ในการคิดและแก้ปัญหาเมื่อเกิดข้อผิดพลาด)

• Thinking Process: Validate target path and required structure before writing files.
• Fallback Strategy: If file creation fails, stop and return partial result report with failed paths.
• Self-Review: Re-scan docs tree and verify all 8 required files exist.
• Output Constraints: Return concise generation report and created file list.

Definition of Done (DoD) Checklist

• All 8 required files created at exact paths
• Required headings match template 1:1 in each file
• Existing files preserved according to overwrite policy
• Cross-file references validated
• Generation report produced

Anti-patterns / Pitfalls

• ⛔ Don't: Change numbering scheme (00..07) or filename contract
• ⚠️ Watch out for: OS path separator differences and case sensitivity
• 💡 Instead: Normalize paths and enforce deterministic path checks

Reference Links & Examples

• Example target layout: D:/B3F_Intelligence_Engine/docs/...
• Related: templates/project-context-template.md

Versioning & Changelog

• Version: 1.0.0
• Changelog:
  • 2026-02-23: Initial skill for shift-left docset scaffolding (8-file contract)