Meta-Initialization Skill

Evidence Produced

Inputs

Outputs

Capability contract

Read/search are required. Creating directories or documents requires explicit project-initialisation scope; never overwrite existing artefacts without inspection.

Degraded mode

Fallback with incomplete context: produce a provisional profile and question register, not a falsely definitive methodology.

Decision rules

Domain anti-patterns

• Selecting Agile because requirements are missing. Fix: gather minimum project facts first.
• Generating every possible document. Fix: justify each artefact by risk and audience.
• Overwriting an existing roadmap. Fix: inspect and propose a merge.
• Treating the method as a label. Fix: define gates, cadence, owners, and evidence.
• Marking provisional assumptions as decisions. Fix: keep an explicit question register.

Process Workflow

flowchart TD
    Start[Run Skill] --> Scan[Scan Project Directory]
    Scan --> Detect[Detect Project Characteristics]
    Detect --> Q1{Existing<br/>methodology.md?}

    Q1 -->|Yes| Confirm[Confirm/Update Methodology]
    Q1 -->|No| Analyze[Analyze Project Type]

    Analyze --> Recommend[Recommend Methodology]
    Recommend --> UserChoice[User Selects Methodology]
    Confirm --> UserChoice

    UserChoice --> Generate[Generate Documentation Roadmap]
    Generate --> Init[Initialize Project Context]
    Init --> Output[Write methodology.md + doc_roadmap.md]
    Output --> Next[Show Next Steps]

    style UserChoice fill:#fff4e1
    style Generate fill:#e1f5ff

Step-by-Step Instructions

Step 1: Scan Project Directory

Scan ../ (parent project root) for indicators:

Project Type Indicators:

• package.json → Node.js/JavaScript project
• composer.json → PHP project
• requirements.txt / pyproject.toml → Python project
• .sln / .csproj → C# .NET project
• pom.xml / build.gradle → Java project
• Cargo.toml → Rust project
• go.mod → Go project

Existing Documentation:

• README.md → Check for methodology mentions
• ARCHITECTURE.md → Check for design approach
• projects/<ProjectName>/_context/methodology.md → Previous methodology selection

Development Artifacts:

• .git/ → Git repository (check for branch strategy)
• docker-compose.yml → Containerized deployment
• .github/workflows/ → CI/CD setup

Log all findings:

[Scan Report]
- Project Type: PHP (composer.json detected)
- Framework: Laravel (composer.json dependencies)
- Database: MySQL (migrations/ directory)
- Deployment: Docker (docker-compose.yml)
- Version Control: Git
- CI/CD: GitHub Actions
- Existing Docs: README.md, ARCHITECTURE.md
- Existing Context: None (first-time setup)

Step 2: Detect Project Characteristics

Based on scan results, determine:

Regulatory/Compliance Indicators

Check for keywords in README.md, documentation:

• "FDA", "FAA", "DOD", "medical device", "aerospace" → Regulated project
• "HIPAA", "GDPR", "SOC2", "PCI-DSS" → Compliance required
• "safety-critical", "life-safety" → Formal V&V needed

Project Maturity

• Greenfield (no existing code): Need comprehensive upfront planning
• Brownfield (existing codebase): Need documentation for existing system
• Startup/MVP: Fast iteration, evolving requirements
• Enterprise: Established processes, likely Waterfall or SAFe

Team Structure

Infer from repository activity (if Git history exists):

• Multiple contributors, PR workflow → Team environment
• Single contributor → Solo developer
• Frequent commits → Agile/iterative
• Infrequent, large commits → Waterfall/milestone-based

Step 3: Recommend Methodology

Based on detected characteristics, recommend:

Recommend Waterfall if:

• ✅ Regulatory/compliance keywords detected
• ✅ Project type: Medical, aerospace, government, automotive
• ✅ Fixed-scope contract language in docs
• ✅ Formal signoff processes mentioned
• ✅ Safety-critical system

Confidence Score: Calculate based on indicators (0-100%)

Example:

[Recommendation: Waterfall] (Confidence: 85%)

Reasons:
1. "FDA" and "medical device" detected in README.md
2. Formal compliance requirements (HIPAA)
3. Fixed-scope project (contract.pdf found)
4. Safety-critical indicators present

Recommended Pipeline:
- 02-requirements-engineering/waterfall/ (Full IEEE 830 SRS)
- 03-design-documentation/ (HLD + LLD for traceability)
- 09-governance-compliance/ (Traceability matrix, audit reports)

Recommend Agile if:

• ✅ Startup/MVP keywords in README
• ✅ Frequent commits (>10/week average)
• ✅ Sprint-based branch naming (feature/, sprint/)
• ✅ User-centric language ("user stories", "epics")
• ✅ No regulatory constraints

Example:

[Recommendation: Agile] (Confidence: 90%)

Reasons:
1. Startup project (package.json: version 0.3.2)
2. Frequent commits (average 15/week)
3. Feature branch workflow detected
4. No regulatory constraints detected
5. README mentions "MVP" and "rapid iteration"

Recommended Pipeline:
- 02-requirements-engineering/agile/ (User stories, backlog)
- 07-agile-artifacts/ (Sprint planning, DoD, DoR)
- Lightweight design docs (HLD only, no LLD)

Recommend Hybrid if:

• ✅ Mixed indicators (regulatory backend + agile frontend)
• ✅ Microservices architecture (some services regulated, others not)
• ✅ SAFe framework indicators
• ✅ Enterprise with agile teams

Example:

[Recommendation: Hybrid] (Confidence: 70%)

Reasons:
1. Microservices architecture detected (docker-compose.yml: 8 services)
2. Backend mentions "payment processing" (regulated)
3. Frontend is React SPA (rapid iteration)
4. Mix of waterfall (API) and agile (UI) branches

Recommended Pipeline:
- Backend: 02-requirements-engineering/waterfall/ (IEEE 830 SRS for payment service)
- Frontend: 02-requirements-engineering/agile/ (User stories for UI)
- Shared: 03-design-documentation/ (Unified HLD)

Step 4: User Selection

Present recommendation and allow user to confirm or override:

==================================================
SDLC-Docs-Engine: Methodology Selection
==================================================

Based on analysis of your project, we recommend:

📋 WATERFALL METHODOLOGY (Confidence: 85%)

Reasons:
- Regulated industry detected (FDA, medical device)
- Fixed-scope project indicators
- Safety-critical system

This recommendation suggests:
✅ Comprehensive upfront requirements (IEEE 830 SRS)
✅ Formal design documentation (HLD + LLD)
✅ Traceability matrix and audit reports
✅ Verification & Validation per IEEE 1012

==================================================

Do you want to:
[1] Accept recommendation (Waterfall)
[2] Choose Agile instead
[3] Choose Hybrid approach
[4] Show detailed comparison
[5] Skip methodology selection (manual setup)

Your choice:

Step 5: Generate Documentation Roadmap

Based on selected methodology, create doc_roadmap.md:

For Waterfall Projects:

# Documentation Roadmap: [Project Name]

**Methodology:** Waterfall
**Selected:** [Date]
**Rationale:** [Brief explanation from detection]

## Active Documentation Pipelines

### Phase 01: Strategic Vision (Optional but Recommended)
- [ ] 01-prd-generation → Product Requirements Document

### Phase 02: Requirements Engineering (MANDATORY)
- [ ] 02-requirements-engineering/waterfall/01-initialize-srs
- [ ] 02-requirements-engineering/waterfall/02-context-engineering
- [ ] 02-requirements-engineering/waterfall/03-descriptive-modeling
- [ ] 02-requirements-engineering/waterfall/04-interface-specification
- [ ] 02-requirements-engineering/waterfall/05-feature-decomposition
- [ ] 02-requirements-engineering/waterfall/06-logic-modeling
- [ ] 02-requirements-engineering/waterfall/07-attribute-mapping
- [ ] 02-requirements-engineering/waterfall/08-semantic-auditing

### Phase 03: Design Documentation (MANDATORY)
- [ ] 03-design-documentation/01-high-level-design
- [ ] 03-design-documentation/02-low-level-design
- [ ] 03-design-documentation/03-api-specification

### Phase 05: Testing Documentation (MANDATORY)
- [ ] 05-testing-documentation/01-test-strategy
- [ ] 05-testing-documentation/02-test-plans

### Phase 09: Governance & Compliance (MANDATORY)
- [ ] 09-governance-compliance/01-traceability-matrix
- [ ] 09-governance-compliance/02-audit-reports
- [ ] 09-governance-compliance/03-compliance-docs (if HIPAA/GDPR/SOC2)

## Disabled Pipelines

❌ **Phase 07: Agile Artifacts** (Not applicable for Waterfall)
❌ **Phase 02: Agile Requirements** (Using Waterfall SRS instead)

## Execution Order

1. **Week 1-2:** Phase 02 (Requirements) - Generate IEEE 830 SRS
2. **Week 3-4:** Phase 03 (Design) - HLD and LLD
3. **Week 5:** Phase 05 (Testing) - Test strategy and plans
4. **Week 6:** Phase 09 (Governance) - Traceability and audits

**Total Estimated Time:** 6 weeks for complete documentation suite

## Next Steps

Run: 02-requirements-engineering/waterfall/01-initialize-srs

For Agile Projects:

# Documentation Roadmap: [Project Name]

**Methodology:** Agile (Scrum)
**Selected:** [Date]
**Rationale:** [Brief explanation]

## Active Documentation Pipelines

### Phase 01: Strategic Vision (MANDATORY for Agile)
- [ ] 01-strategic-vision/01-prd-generation → Lightweight PRD

### Phase 02: Requirements Engineering (MANDATORY)
- [ ] 02-requirements-engineering/agile/01-user-story-generation
- [ ] 02-requirements-engineering/agile/02-acceptance-criteria
- [ ] 02-requirements-engineering/agile/03-story-mapping
- [ ] 02-requirements-engineering/agile/04-backlog-prioritization

### Phase 03: Design Documentation (Lightweight)
- [ ] 03-design-documentation/01-high-level-design (HLD only, skip LLD)

### Phase 07: Agile Artifacts (MANDATORY)
- [ ] 07-agile-artifacts/01-sprint-planning
- [ ] 07-agile-artifacts/02-definition-of-done
- [ ] 07-agile-artifacts/03-definition-of-ready

### Phase 08: End-User Documentation (Post-MVP)
- [ ] 08-end-user-documentation/01-user-manual

## Disabled Pipelines

❌ **Phase 02: Waterfall SRS** (Using Agile user stories instead)
❌ **Phase 09: Formal Governance** (Lightweight traceability via story tags)

## Execution Order

1. **Sprint 0:** Phase 01 (Vision) + Phase 02 (User Stories)
2. **Sprint 0:** Phase 03 (HLD) - Architectural overview
3. **Sprint 1-N:** Phase 07 (Agile Artifacts) - Ongoing per sprint
4. **Post-MVP:** Phase 08 (User Docs)

**Total Estimated Time:** 1-2 sprints for initial setup, then continuous

## Next Steps

Run: 01-strategic-vision/01-prd-generation
Then: 02-requirements-engineering/agile/01-user-story-generation

Step 6: Initialize Project Context

Check if projects/<ProjectName>/_context/ exists:

If missing:

mkdir -p projects/<ProjectName>/_context
echo "Project context directory created."

If exists:

[INFO] Project context directory already exists.
Checking for existing files...

Found:
- vision.md (last modified: 2026-01-15)
- features.md (last modified: 2026-01-20)

Missing:
- methodology.md (will be created)
- doc_roadmap.md (will be created)

Step 7: Write Output Files

File 1: projects/<ProjectName>/_context/methodology.md

Use template from templates/methodology.md.template (populated with detection results).

File 2: projects/<ProjectName>/_context/doc_roadmap.md

Use template from templates/doc_roadmap.md.template (populated based on methodology).

File 3: projects/<ProjectName>/_context/project_profile.md

# Project Profile

**Generated:** [Date]
**Project Type:** [Detected type]
**Framework:** [Detected framework]
**Database:** [Detected database]
**Deployment:** [Detected deployment]

## Characteristics

- **Regulatory Constraints:** [Yes/No - list standards]
- **Team Size:** [Inferred from git history]
- **Development Pace:** [Rapid/Moderate/Methodical]
- **Maturity:** [Greenfield/Brownfield/Startup/Enterprise]

## Recommended Methodology

**Selected:** [Waterfall/Agile/Hybrid]
**Confidence:** [XX%]

See `methodology.md` for full rationale.

Resources

• templates/methodology.md.template: Template for methodology selection
• templates/doc_roadmap.md.template: Template for documentation roadmap
• references/methodology-decision-tree.md: Detailed decision criteria
• references/detection-rules.md: Project characteristic detection rules

Common Pitfalls

❌ Skipping this skill

• Jumping directly to Phase 02 without methodology selection leads to wrong documentation approach

❌ Overriding recommendation without justification

• If you choose Agile for a regulated project, document WHY (e.g., regulatory approval already obtained)

❌ Not updating roadmap when project changes

• Re-run this skill if project characteristics change (e.g., startup gets FDA approval)

❌ Ignoring hybrid recommendations

• If recommended Hybrid, don't force pure Waterfall or Agile

Verification Checklist

Before proceeding to Phase 01/02:

• projects/<ProjectName>/_context/methodology.md exists and is populated
• projects/<ProjectName>/_context/doc_roadmap.md exists with checklist
• projects/<ProjectName>/_context/project_profile.md exists
• Methodology selection is documented with rationale
• Next steps are clear (which skill to run next)
• Team agrees with methodology choice (if applicable)

Integration with Other Phases

This skill enables:

• Phase 01 (Strategic Vision): Knows whether to generate PRD (Agile) or skip (Waterfall starts with SRS)
• Phase 02 (Requirements): Activates correct pipeline (waterfall/ or agile/)
• Phase 03 (Design): Determines depth (full HLD+LLD for Waterfall, lightweight HLD for Agile)
• Phase 07 (Agile Artifacts): Only activates if methodology is Agile or Hybrid
• Phase 09 (Governance): Determines formality level (full RTM for Waterfall, lightweight for Agile)

Upstream Dependencies:

• None (this is the first skill to run)

Downstream Consumers:

• All other phases read methodology.md to determine their execution mode

Example Output

See templates/ directory for complete examples:

• methodology.md.example - Waterfall selection for medical device
• methodology.md.example-agile - Agile selection for startup
• methodology.md.example-hybrid - Hybrid for enterprise SaaS

Maintenance & Updates

When to re-run this skill:

• Project characteristics change significantly (e.g., startup becomes enterprise)
• Regulatory status changes (e.g., FDA approval required mid-project)
• Team decides to switch methodologies
• Major pivot in product direction

Safe to re-run: Yes, this skill will prompt before overwriting existing files.

Last Updated: 2026-02-07 Skill Version: 1.0.0 Maintained by: Peter Bamuhigire