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)

Type	Focus Area	Required Scenarios / Mocks
Unit	Path Builder	Validate generated paths match exact folder/file contract
Integration	Filesystem Ops	Create docs tree in clean and partially-existing repositories
E2E	Team Workflow	Generate docs, fill sections, review, and approve before coding
Performance	Bulk Scaffolding	Create docsets for multiple projects within acceptable runtime
Security	Path Safety	Block path traversal and unsafe overwrite behavior
Frontend	N/A	Not applicable for this skill

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)