Component Research

TBC Component Research

Process for determining if a To-Be-Continuous (TBC) component fits a use case or requires customization.

Flow

Research → Evaluate → AskUserQuestion → User selects → Proceed

Purpose

This skill provides a systematic research process to evaluate TBC framework capabilities against user requirements. Use this BEFORE generating any configuration to ensure the correct solution path.

When to Use

• Before generating .gitlab-ci.yml with TBC
• When user requests functionality that may or may not be covered by TBC
• When deciding between TBC template, variant, or custom solution
• When user asks for something and the approach needs validation

Solution Priority Hierarchy

ALWAYS follow this priority order. Higher priority = preferred solution.

Key Principle: The user may request a solution (e.g., "custom script") but be incorrect. This process disciplines correct framework usage by evaluating ALL options before accepting user's proposed approach.

Decision Process Overview

User Request
    │
    ▼
╔═══════════════════════════════════════════╗
║  IDENTIFY CORE NEED (MANDATORY FIRST)     ║
║  Invoke identify-core-need skill          ║
╚═══════════════════════════════════════════╝
    │
    ▼
╔═══════════════════════════════════════════╗
║  DEEP RESEARCH PHASE (MANDATORY)          ║
║  See references/decision-process.md       ║
╚═══════════════════════════════════════════╝
    │
    ▼
Evaluate Priority 1-6 with evidence
    │
    ▼
╔═══════════════════════════════════════════╗
║  ASK USER FOR CLARIFICATION               ║
║  Present options using AskUserQuestion    ║
╚═══════════════════════════════════════════╝
    │
    ▼
Proceed based on user selection

Quick Decision Steps

Step 1: Identify Core Need

Invoke the identify-core-need skill before proceeding.

This skill handles:

• Clarifying ambiguous requests (AskUserQuestion)
• Applying Behavioral Principles (no artificial distinctions)
• Extracting Core Need (action + target + triggers)
• Documenting Validation Log

Only proceed to Step 2 when Core Need is clearly defined with Validation Log complete.

Step 2: Search Template Catalog

Read schemas/_meta.json from building-with-tbc skill for complete template inventory. Check:

• Template names and versions
• Available variants
• Project paths for YML download

Step 3: Evaluate Template Fit

For each potentially matching template:

1. Read schemas/{template}.json for inputs
2. Check if required inputs match use case
3. Check if optional inputs cover customization needs
4. Review available variants in references/variantes.md

Step 4: Deep Research (If Partial Match)

When template partially covers the need, execute Deep Research Phase:

1. Download actual YML from GitLab using URL pattern:

   https://gitlab.com/{project}/-/raw/{version}/{file}
   

2. Analyze YML content: stages, jobs, scripts, tools, extension points

3. WebSearch tool documentation for underlying tools

4. Cross-reference user need vs template vs tool capabilities

See references/decision-process.md for complete Deep Research protocol.

Step 5: Present Options to User

CRITICAL: Do NOT decide autonomously. Present findings and ask user to choose.

After gathering evidence, use AskUserQuestion tool to present viable options:

AskUserQuestion:
  header: "TBC Approach"
  question: "Based on research, which approach for {use case}?"
  options:
    - label: "{Template} direct"
      description: "Covers {X}% of requirements. {brief evidence}"
    - label: "{Template} + variant"
      description: "Adds {capability}. {brief evidence}"
    - label: "Custom step"
      description: "TBC doesn't cover {gap}. Requires manual job."

Guidelines for AskUserQuestion:

• Maximum 4 options (tool limit)
• Each option must include evidence from research
• Describe trade-offs clearly in descriptions
• Order options by Priority (1-6) - best option first
• User can always select "Other" for alternatives

Example Question:

header: "TBC Approach"
question: "Which approach for Docker image build with Trivy scan?"
options:
  - label: "docker template"
    description: "Builds and pushes images. Trivy scan via TBC_DOCKER_SCAN_IMAGE=true"
  - label: "docker + custom scan"
    description: "Use docker template but add separate Trivy job for more control"
  - label: "Custom Dockerfile job"
    description: "Full control but loses TBC caching and best practices"

Output Format

After user selects an option, document the decision path:

## Decision Path

User Request: "{request}"
    │
    ▼
Core Need: {action} + {target}
    │
    ▼
Templates Checked: {list}
    │
    ▼
Match Analysis: {findings}
    │
    ▼
Options Presented: {options shown to user}
    │
    ▼
User Selection: {user's choice}
    │
    ▼
Proceeding with: Priority {N} - {solution}

Evidence:
- {source-1}: {finding}
- {source-2}: {finding}

Reference Files

Integration with building-with-tbc

After user selects an option via AskUserQuestion:

1. Document decision path with user's selection
2. If TBC component selected → invoke building-with-tbc skill to generate config
3. If custom step selected → document WHY TBC doesn't fit before proceeding

Common Scenarios

Scenario: Template Exists but Partial Fit

Follow Deep Research to check if:

• Template extension points (before_script, scripts-dir) can enable the feature
• Underlying tool supports the requirement
• Variant pattern from other template can be applied

Scenario: User Requests Custom Script

Do NOT accept immediately. Execute full research process:

1. Identify what user actually needs
2. Check if any TBC template covers it
3. Check variants
4. Only if documented failure → accept custom approach

Scenario: Multiple Templates Possible

Compare each template's fit:

• Which covers more requirements?
• Which has better extension points?
• Which has relevant variants?