notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/domain-research.md
View on GitHub---
description: "Discover and classify subdomains for pipeline generation."
user-invocable: false
allowed-tools:
- Read
- Write
- Bash
- Grep
- Glob
- Edit
- Agent
routing:
triggers:
- research domain
- discover subdomains
- domain decomposition
- what pipelines
- domain research
pairs_with:
- pipeline-scaffolder
- codebase-overview
complexity: Medium
category: meta
---
# Domain Research Skill
## Overview
This skill answers: **What subdomains exist in this target domain, and what kind of pipeline does each one need?**
The skill implements a **Research-Classify-Map-Produce** pattern: broad parallel discovery narrows into structured classification, then maps to pipeline chains, then produces a Component Manifest that the chain-composer skill uses to finalize and scaffold pipeline components.
This is the first step in the self-improving pipeline generator (see `adr/self-improving-pipeline-generator.md`).
---
## Instructions
### Inputs
| Input | Source | Required |
|-------|--------|----------|
| Domain name | User prompt (e.g., "Prometheus", "RabbitMQ", "Terraform") | Yes |
| Run ID | Generated by the pipeline orchestrator or `uuidgen` | Yes |
| Operator profile | Detected by `pipeline-context-detector` hook or pipeline-orchestrator Phase 0 | No (default: Personal) |
| Environmental state JSON | From `pipeline-context-detector` hook | No (Phase 1 can scan directly) |
### Phase 1: DISCOVER (Parallel Multi-Agent — Rule 12 Mandatory)
**Goal**: Build a broad, multi-perspective understanding of the target domain. Breadth of research directly determines the quality of subdomain discovery — this is why parallel agents are mandatory, not optional. A/B testing proved parallel research eliminates a 1.40-point gap in Examples quality (see `adr/pipeline-creator-ab-test.md`). Parallel research is **mandatory** because sequential research produces shallower, less diverse findings.
**Default N = 4 agents.** Override with `--research-agents N` (minimum 2, maximum 6).
**Step 1: Prepare research context**
Create the run directory and shared context block:
```bash
mkdir -p /tmp/pipeline-{run-id}/phase-1-research
```
Assemble shared context from:
- The domain name and any user-provided context about what they need
- The ADR from pipeline-orchestrator Phase 0 (if it exists)
- Environmental state JSON (if available from pipeline-context-detector)
**Step 2: Dispatch 4 parallel research agents**
Launch **all 4 agents simultaneously** using the Task tool. Each agent receives the shared context block and saves findings to a separate artifact file. Each has a 5-minute timeout.
**Agent 1: Domain Expert**
- Investigate: What are the subdomains of this domain? What tasks do practitioners commonly perform? What are the natural workflow boundaries?
- Method: Use domain knowledge, web search if available, and reasoning about the domain's structure
- Output: List of candidate subdomains with descriptions and common tasks for each
- Save to: `/tmp/pipeline-{run-id}/phase-1-research/agent-1-domain-expert.md`
**Agent 2: Existing Inventory**
- Investigate: What skills, skill references, hooks, and scripts already exist in this repository for this domain or closely related domains? Repo agents are retired (plan 009); their domain expertise now lives in skill references such as `skills/infrastructure/kubernetes/references/prometheus-grafana.md`.
- Method: Search `skills/INDEX.json` for matching skill names and triggers. Grep `skills/*/*/references/*.md` and each skill's Reference Loading Table for domain keywords. Search `skills/meta/do/references/routing-tables.md` for matching skill routes. Glob for file patterns matching the domain name. Check `agents/INDEX.local.json` only for private overlay agents.
- Output: Inventory of existing components with relevance assessment (full match, partial match, tangential)
- Save to: `/tmp/pipeline-{run-id}/phase-1-research/agent-2-existing-inventory.md`
**Agent 3: Workflow Patterns**
- Investigate: For each candidate subdomain (or domain-level if subdomains aren't yet known), what pipeline patterns from the step menu fit?
- Method: Read `skills/process/workflow/references/pipeline-scaffolder/references/step-menu.md`. For each step family, assess whether the domain's tasks match the "When To Use" criteria. Identify which step families are most relevant.
- Output: Mapping of domain task patterns to step menu families, with reasoning
- Save to: `/tmp/pipeline-{run-id}/phase-1-research/agent-3-workflow-patterns.md`
**Agent 4: Reference Research**
- Investigate: What reference documentation would subdomain skills need? What external specs, APIs, or tools define this domain? What domain-specific validators exist or could be built?
- Method: Identify key domain concepts that would need reference files. List external documentation sources. Identify domain artifacts that could be validated deterministically (e.g., PromQL syntax, HCL validation, YAML schema).
- Output: Reference file recommendations and deterministic validation opportunities
- Save to: `/tmp/pipeline-{run-id}/phase-1-research/agent-4-reference-research.md`
**Why parallel is mandatory**: Parallel dispatch forces diverse perspectives from the start. Agents work independently without seeing each other's partial results, staying free of anchoring bias. Testing proved 4-agent parallel produces measurably better Examples coverage than sequential dispatch.
**Step 3: Collect and merge research artifacts**
After all agents complete (at least 3 of 4 must succeed), merge findings into a single research compilation at `/tmp/pipeline-{run-id}/phase-1-research/content.md`.
Create the Phase 1 dual-layer artifact:
`/tmp/pipeline-{run-id}/phase-1-research/manifest.json`:
```json
{
"schema": "research-artifact",
"step": "RESEARCH",
"phase": 1,
"status": "complete",
"metrics": {
"agents_dispatched": 4,
"agents_completed": 4,
"candidate_subdomains": 0,
"existing_components_found": 0
},
"inputs": ["adr/pipeline-{name}.md"],
"outputs": ["content.md", "agent-1-domain-expert.md", "agent-2-existing-inventory.md", "agent-3-workflow-patterns.md", "agent-4-reference-research.md"],
"timestamp": "",
"tags": ["{domain-name}", "research", "domain-decomposition"]
}
```
Update `metrics.candidate_subdomains` and `metrics.existing_components_found` with actual counts.
**Gate**: All of the following must be true before proceeding:
- At least 3 of 4 research agents completed successfully (Rule 12 gate)
- Research compilation file exists at `/tmp/pipeline-{run-id}/phase-1-research/content.md`
- At least 1 candidate subdomain identified
- `manifest.json` written with `status: "complete"`
If fewer than 3 agents completed: set `status: "partial"`, report which agents failed and why, and proceed with available data only if at least 1 subdomain was identified. Otherwise STOP and report failure to pipeline-orchestrator.
### Phase 2: CLASSIFY
**Goal**: For each candidate subdomain from Phase 1, assign a task type, complexity tier, reuse assessment, and required references. This phase transforms raw research findings into structured classifications that Phase 3 can map to pipeline chains. **Discovery logic**: Subdomains are discovered through research, not hardcoded. Why? Hardcoded lists miss domain-specific nuances and become stale. The whole point of this skill is that it adapts to any domain.
**Step 1: Load classification reference**
Read `skills/process/workflow/references/domain-research/references/task-type-guide.md` for task type definitions and canonical chain patterns. This file defines the 8 task types and provides examples of how each maps to step menu families.
**Step 2: Classify each subdomain**
For each candidate subdomain discovered in Phase 1, determine:
**Task Type** (exactly one primary, optionally one secondary):
| Task Type | Description | Key Indicator |
|-----------|-------------|---------------|
| `generation` | Produces new artifacts (code, config, docs) | "Write me a...", "Create a...", "Generate..." |
| `review` | Evaluates existing artifacts against criteria | "Review this...", "Check if...", "Audit..." |
| `debugging` | Diagnoses and resolves failures | "Why is X broken?", "Fix this...", "Troubleshoot..." |
| `operations` | Manages running systems (deploy, scale, monitor) | "Deploy...", "Scale...", "Restart...", "Monitor..." |
| `configuration` | Produces or validates configuration artifacts | "Configure...", "Set up...", "Add rule for..." |
| `analysis` | Investigates data/systems to produce insights | "Analyze...", "What's the impact of...", "Compare..." |
| `migration` | Transforms between versions, formats, or systems | "Migrate from...", "Upgrade...", "Convert..." |
| `monitoring` | Ongoing observation with threshold-based alerting | "Alert when...", "Watch for...", "Track..." |
When a subdomain's tasks span two types (e.g., alerting is `configuration` + `monitoring`), assign the primary type based on the most common practitioner workflow and note the secondary type.
**Complexity** (based on expected pipeline chain length):
| Complexity | Chain Length | Characteristics |
|------------|-------------|-----------------|
| Simple | 3-5 steps | Linear flow, single output type, no cross-domain dependencies |
| Medium | 5-8 steps | May include review or validation loops, 1-2 output types |
| Complex | 8+ steps | Cross-domain delegation, safety gates, multiple output types, experimentation |
**Reuse Potential** — For each subdomain, check the existing inventory (from Agent 2). Always verify existing coverage before marking anything as "New" (Rule 9: Reuse Before Create). Why? Duplicated domain expertise drifts. The generator biases toward binding new skills to existing skill references.
- **Full reuse** (80%+): Existing skill reference AND skill cover this subdomain. Skip it or note for enhancement only.
- **Partial reuse** (40-79%): Existing skill reference covers the domain but no skill for this specific subdomain. Create new skill, bind it to the existing reference.
- **New** (<40%): No existing components meaningfully cover this. Needs new skill and possibly a new shared domain reference.
**Required References** — What domain knowledge files would the subdomain skill need?
- Pattern libraries (e.g., `promql-patterns.md`, `terraform-module-patterns.md`)
- Configuration schemas (e.g., `alertmanager-routing.md`, `helm-values-schema.md`)
- Best practices guides (e.g., `metric-naming-conventions.md`)
**Required Scripts** — What deterministic validators would the subdomain skill need?
- Syntax validators (e.g., `promql-validator.py`, `hcl-lint.py`)
- Schema validators (e.g., `yaml-schema-check.py`)
- Convention checkers (e.g., `naming-convention-check.py`)
**Step 3: Produce classification artifact**
Create the Phase 2 dual-layer artifact:
`/tmp/pipeline-{run-id}/phase-2-classify/manifest.json`:
```json
{
"schema": "structured-corpus",
"step": "CLASSIFY",
"phase": 2,
"status": "complete",
"metrics": {
"subdomains_classified": 0,
"full_reuse": 0,
"partial_reuse": 0,
"new_components": 0
},
"inputs": ["../phase-1-research/content.md"],
"outputs": ["content.md"],
"timestamp": "",
"tags": ["{domain-name}", "classification", "subdomain"]
}
```
`/tmp/pipeline-{run-id}/phase-2-classify/content.md` — Structured classification table:
```markdown
# Subdomain Classification: {Domain}
## Classification Summary
| Subdomain | Task Type | Secondary | Complexity | Reuse | Existing Reference |
|-----------|-----------|-----------|------------|-------|--------------------|
| {name} | {type} | {type|none} | {Simple|Medium|Complex} | {Full|Partial|New} | {skill/references/file.md|none} |
## Detailed Classifications
### {Subdomain Name}
- **Task Type**: {primary} (secondary: {secondary|none})
- **Complexity**: {tier} — {rationale}
- **Reuse**: {assessment} — {which existing components and what % coverage}
- **Required References**: {list of reference files needed}
- **Required Scripts**: {list of deterministic validators needed}
- **Key Tasks**: {what practitioners do in this subdomain}
```
**Gate**: All of the following must be true before proceeding:
- Every candidate subdomain from Phase 1 has a task_type assigned
- Every candidate subdomain has a complexity tier
- Every candidate subdomain has a reuse assessment (checked against Agent 2's inventory)
- At least 2 subdomains classified (if only 1 found, reconsider whether the domain is too narrow for decomposition — report to pipeline-orchestrator and ask whether to proceed as single-pipeline)
- `manifest.json` written with `status: "complete"`
### Phase 3: MAP (Compose Preliminary Chains)
**Goal**: For each classified subdomain, select steps from the step menu and compose a preliminary pipeline chain. These are draft chains — the chain-composer skill validates and finalizes them. **Type compatibility is mandatory**: Every adjacent step pair must have compatible output-to-input types. Why? Invalid types produce broken chains. Always validate type compatibility.
**Step 1: Load step menu**
Read `skills/process/workflow/references/pipeline-scaffolder/references/step-menu.md` for the complete step inventory with output schemas and type compatibility.
**Step 2: Compose chains**
For each classified subdomain, build a preliminary chain by:
1. **Start with ADR** (mandatory — every chain starts with ADR per composition rules)
2. **Select research steps** based on what the subdomain needs to know before generating output:
- Domain needing broad investigation: GATHER or RESEARCH (parallel)
- Domain needing codebase analysis: SCAN or SEARCH
- Domain needing external data: FETCH
3. **Select structuring steps** to organize research into usable form:
- Most generation tasks: COMPILE (structure findings) or OUTLINE (define output shape)
- Decision-heavy tasks: ASSESS or BRAINSTORM
- Architecture tasks: MAP
4. **Select generation/execution steps** based on task type:
- `generation`: GENERATE (possibly preceded by GROUND for audience-specific content)
- `review`: REVIEW (parallel 3+ lenses) then AGGREGATE
- `debugging`: SEARCH then PLAN then EXECUTE
- `operations`: PROBE then PLAN then EXECUTE
- `configuration`: GENERATE then CONFORM
- `analysis`: RESEARCH then SYNTHESIZE
- `migration`: CHARACTERIZE then PLAN then TRANSFORM then EXECUTE
- `monitoring`: GENERATE then MONITOR (or PROBE for health checks)
5. **Select validation steps** based on whether output is deterministically checkable:
- Has a syntax/schema: LINT or CONFORM
- Has testable behavior: VERIFY
- Has quality criteria: VALIDATE
- Add REFINE (max 3 cycles) after any validation step that can fail
6. **Apply profile gates** — note which steps are profile-dependent. Record as annotations on the chain, not hard inclusions. Why? Read the operator profile from pipeline context but keep all research steps ungated — research itself is read-only and harmless across all profiles. The profile information is passed through to the Component Manifest so downstream skills (chain-composer, scaffolder) can apply the correct safety gates.
- APPROVE: Work/Production only
- GUARD + SNAPSHOT: Work/Production only for state changes
- SIMULATE: Production only (optional elsewhere)
- NOTIFY: CI/Work/Production (skip in Personal)
7. **Check for cross-domain dependencies**:
- Does this subdomain need expertise from another domain? Add DELEGATE
- Does this subdomain's output feed into another subdomain's input? Note the dependency
**Step 3: Validate chains against type compatibility**
For each preliminary chain, verify adjacent steps have compatible output-to-input types using the Type Compatibility Matrix from the ADR:
```
Step A produces → Schema X
Step B consumes → [list of acceptable schemas]
If Schema X is in Step B's consumes list → compatible
Otherwise → flag the incompatibility and adjust
```
When incompatibility is found, insert a bridging step. Common bridges:
- Research Artifact needs to become Structured Corpus: insert COMPILE
- Multiple Verdicts need to become one: insert AGGREGATE
- Generation Artifact needs Verdict before next step: insert VALIDATE
If no bridge works, restructure the chain. **Always validate type compatibility.**
**Step 4: Produce mapping artifact**
`/tmp/pipeline-{run-id}/phase-3-map/manifest.json`:
```json
{
"schema": "decision-record",
"step": "MAP",
"phase": 3,
"status": "complete",
"metrics": {
"chains_composed": 0,
"profile_gated_steps": 0,
"cross_domain_delegates": 0,
"type_incompatibilities_resolved": 0
},
"inputs": ["../phase-2-classify/content.md"],
"outputs": ["content.md"],
"timestamp": "",
"tags": ["{domain-name}", "chain-composition", "step-menu"]
}
```
`/tmp/pipeline-{run-id}/phase-3-map/content.md`:
```markdown
# Preliminary Pipeline Chains: {Domain}
## Chain Summary
| Subdomain | Chain | Profile Gates |
|-----------|-------|---------------|
| {name} | ADR -> STEP -> STEP -> ... -> OUTPUT | {list of profile-dependent steps} |
## Detailed Chains
### {Subdomain Name}
**Task type**: {type} | **Complexity**: {tier}
**Chain**: `ADR -> {step} -> {step} -> ... -> OUTPUT`
| Step | Purpose | Output Schema | Profile Gate |
|------|---------|---------------|-------------|
| ADR | Persistent reference | - | None |
| {step} | {why this step} | {schema} | {None|Work|Production} |
**Cross-domain dependencies**: {none | DELEGATE to {domain} for {reason}}
**Type compatibility**: All adjacent steps validated / {list any resolved incompatibilities}
```
**Gate**: All of the following must be true before proceeding:
- Every classified subdomain has a preliminary chain
- Every chain starts with ADR and ends with OUTPUT (or REPORT for analysis tasks)
- No unresolved type compatibility issues remain (all incompatibilities resolved or accepted with explicit bridge steps)
- All profile-gated steps are annotated (not hard-included)
- `manifest.json` written with `status: "complete"`
### Phase 4: PRODUCE (Component Manifest)
**Goal**: Compile all findings into the final Component Manifest — the single document that tells pipeline-scaffolder and chain-composer exactly what to build.
**Step 1: Determine domain reference strategy**
Repo agents are retired (plan 009): domain expertise lives in a skill reference, and dispatched work runs on a fresh `general-purpose` worker told which reference to load. Based on the existing inventory (Phase 1, Agent 2) and reuse assessments (Phase 2):
- If an existing skill reference covers 70%+ of the domain: **Bind it**. All new subdomain skills load this reference. Note its path (`{skill}/references/{file}.md`) and what gaps it has (if any).
- If no existing reference covers the domain: **Write one new shared domain reference** (`{domain}-domain-knowledge.md`). Define its purpose, expertise list, and which subdomain skills load it.
- **Use one domain reference for the entire domain.** Why? Duplicated domain expertise drifts; one reference loaded by N skills stays consistent. The architecture is "1 reference : N skills" not "N references : N skills".
- Plan a private overlay agent only when the owner asks for one. It lives outside the repo index, in `agents/INDEX.local.json`.
**Step 2: Compile shared resources**
Identify resources that span multiple subdomains:
- **Shared references**: Domain knowledge files useful across multiple subdomain skills (e.g., `{domain}-domain-knowledge.md`)
- **Shared scripts**: Validators that multiple subdomain skills invoke (e.g., `{domain}-syntax-validator.py`)
- **Shared hooks**: Detectors that trigger multiple subdomain skills based on context
**Step 3: Write the Component Manifest**
`/tmp/pipeline-{run-id}/phase-4-produce/manifest.json`:
```json
{
"schema": "orchestration-manifest",
"step": "PRODUCE",
"phase": 4,
"status": "complete",
"metrics": {
"subdomains": 0,
"new_skills": 0,
"new_domain_references": 0,
"reused_domain_references": 0,
"reference_files": 0,
"scripts": 0
},
"inputs": [
"../phase-1-research/content.md",
"../phase-2-classify/content.md",
"../phase-3-map/content.md"
],
"outputs": ["content.md"],
"timestamp": "",
"tags": ["{domain-name}", "component-manifest", "pipeline-generation"]
}
```
`/tmp/pipeline-{run-id}/phase-4-produce/content.md`:
```markdown
# Component Manifest: {Domain}
## Domain
- **Name**: {domain}
- **Description**: {1-2 sentence domain summary}
- **Operator Profile**: {detected profile}
- **Subdomains Discovered**: {count}
## Domain Reference Strategy
### Bound Reference
- **Path**: {skill}/references/{file}.md
- **Coverage**: {what it covers, what gaps remain}
- **Binding**: All subdomain skills below load this reference
### New Shared Reference (if needed)
- **Name**: {domain}-domain-knowledge.md
- **Purpose**: {single-purpose description}
- **Expertise**: [{3-6 items}]
- **Loaded By**: [{skill-1}, {skill-2}, ...]
### Worker
- `general-purpose` (or the owner-requested private overlay agent)
## Subdomain Skills
### {Subdomain 1}: {name}
- **Skill name**: {domain}-{subdomain}
- **Task type**: {primary} (secondary: {secondary|none})
- **Complexity**: {tier}
- **Preliminary chain**: `ADR -> {steps} -> OUTPUT`
- **Domain reference**: {path} (bound|new); worker `general-purpose`
- **References needed**:
- `references/{file}.md` — {purpose}
- **Scripts needed**:
- `scripts/{file}.py` — {purpose}
- **Profile-gated steps**: {list|none}
- **Cross-domain delegates**: {list|none}
### {Subdomain 2}: {name}
(same structure)
## Shared Resources
### References (span multiple subdomains)
- `{domain}-domain-knowledge.md` — {what it contains}
### Scripts (shared validators)
- `scripts/{domain}-{function}.py` — {what it validates}
### Hooks
- `hooks/{domain}-context-detector.py` — {what it detects, which skills it triggers}
## Routing Entries (to be created by routing-table-updater)
- Domain reference signals: [{trigger keywords}] (rows in each skill's Reference Loading Table)
- Skill triggers per subdomain: [{per-skill triggers}]
```
**Gate**: All of the following must be true before proceeding:
- Component Manifest file exists at `/tmp/pipeline-{run-id}/phase-4-produce/content.md`
- At least 2 subdomains listed with complete metadata
- Every subdomain has: skill name, task type, complexity, preliminary chain, domain reference
- Domain reference strategy documented (bind vs. create, with rationale)
- Shared resources identified
- `manifest.json` written with `status: "complete"`
If gate passes: Report completion to the pipeline orchestrator (`pipeline-orchestrator.md`). The Component Manifest is the handoff artifact for the chain-composer skill.
---
## Error Handling
### Error: Domain Too Narrow
**Cause**: Phase 1 discovers only 1 subdomain, or all discovered subdomains collapse to the same task type.
**Solution**: Report to the pipeline orchestrator (`pipeline-orchestrator.md`) with findings. The domain may not need decomposition — it may be a single-pipeline domain. Ask: "Only 1 subdomain found for {domain}. Proceed as single pipeline or broaden the domain scope?"
### Error: Research Agent Timeout
**Cause**: One or more parallel agents in Phase 1 exceed the 5-minute timeout.
**Solution**: If 3+ agents completed, proceed with available data. If fewer than 3, retry the failed agent(s) once with a simplified prompt. If retry fails, proceed with available data and note the gap in the research compilation. Never retry more than once — move forward with what you have.
### Error: No Existing Inventory Match
**Cause**: Agent 2 finds zero existing components for the domain.
**Solution**: This is valid for novel domains. Set all subdomains to reuse potential "New" and note that a new shared domain reference will be needed. The Component Manifest should flag this prominently so the scaffolder writes the reference.
### Error: Ambiguous Task Type
**Cause**: A subdomain's tasks span 3+ task types with no clear primary.
**Solution**: Split the subdomain. If "Prometheus operations" covers debugging, monitoring, AND configuration, split into "Prometheus troubleshooting" (debugging), "Prometheus monitoring" (monitoring), and "Prometheus configuration" (configuration). Smaller, focused subdomains produce better pipeline chains than broad, unfocused ones.
### Error: Type Incompatibility in Chain
**Cause**: Phase 3 chain validation finds that step A's output schema doesn't match step B's input requirements.
**Solution**: Insert a bridging step. Common bridges:
- Research Artifact needs to become Structured Corpus: insert COMPILE
- Multiple Verdicts need to become one: insert AGGREGATE
- Generation Artifact needs Verdict before next step: insert VALIDATE
If no bridge works, restructure the chain. Always validate type compatibility.
---
## Source Hierarchy
Research follows a strict source hierarchy. Why? Stale training data is the most common research failure — hallucinated version numbers, deprecated APIs, and removed features all come from treating training data as current documentation.
| Priority | Source | Confidence | When to Use |
|----------|--------|------------|-------------|
| 1 | **MCP/Context7** — current documentation via tool access | HIGH | Always try first. Guaranteed current. Use `resolve-library-id` then `query-docs` for any library research. |
| 2 | **Official documentation** — vendor/project docs via web fetch | HIGH | When Context7 doesn't cover the library, or for vendor-specific configuration guides |
| 3 | **Web search** — general web results | MEDIUM | Last resort. Always verify version numbers against source 1 or 2. Community posts may reference outdated APIs. |
| 4 | **Training data** — model knowledge without external verification | LOW | Only when sources 1-3 are unavailable. MUST be tagged LOW confidence regardless of how certain it appears. |
If a finding comes from training data alone (no external verification), it MUST be tagged LOW confidence. This applies even when the model is highly confident — confidence is not currency without a source.
## Confidence-Level Tagging
Every research finding is tagged with a confidence level. Why? Without explicit confidence, consumers of research output treat all findings as equally reliable — which means a guess from training data carries the same weight as a verified API response. Confidence tagging forces the researcher to assess source quality and forces the consumer to calibrate trust.
### Confidence Levels
| Level | Source Examples | Presentation Rule |
|-------|---------------|-------------------|
| **HIGH** | Official documentation, verified API responses, source code inspection, Context7 query results | Present as authoritative. No caveats needed. |
| **MEDIUM** | Verified web search results, community consensus (multiple independent sources agree), well-maintained third-party docs | Present with source attribution: "According to [source]..." |
| **LOW** | Unverified sources, single blog post, training data without verification, inference from patterns | Present with explicit caveat: "[UNVERIFIED]" prefix. Use cautious language only. |
### Rules
- Every finding in the research output MUST have a confidence tag
- Present LOW confidence findings with explicit "[UNVERIFIED]" prefix — even in summary tables
- If only LOW confidence information is available for a critical decision point, the research output MUST flag this as a **verification gap**: "No high-confidence source found for [topic]. Manual verification required before proceeding."
- When multiple sources disagree, report the disagreement rather than picking one. Tag with the confidence of the highest-quality source and note the conflict.
### Format in Output
```markdown
## Findings
### [Topic]
**Confidence**: HIGH | Source: Context7 query, official docs
[Finding details...]
### [Topic 2]
**Confidence**: LOW | Source: Training data only
[UNVERIFIED] [Finding details...]
> Verification gap: No official documentation found for this behavior.
> Manual verification required before using in production.
```
---
## Use Battle-Tested Libraries Output Section
Research output includes a mandatory section listing problems that seem simple but have battle-tested library solutions. Why? The most expensive bugs come from reimplementing solutions that already exist with years of production hardening, security patches, and edge case coverage. A hand-rolled JWT validator or rate limiter might pass tests but fail under adversarial conditions.
### Format
Every research deliverable MUST include this section, even if empty (with "No hand-roll risks identified for this domain"):
```markdown
## Use Battle-Tested Libraries
| Problem | Library/Solution | Why Not DIY |
|---------|-----------------|-------------|
| [Problem that seems simple] | [Battle-tested solution] | [Specific edge cases or risks of DIY] |
```
### Examples by Domain
**Authentication/Security**:
| Problem | Library | Why Not DIY |
|---------|---------|-------------|
| JWT validation | golang-jwt/jwt, PyJWT | Signature verification edge cases, algorithm confusion attacks |
| Password hashing | bcrypt, argon2 | Timing attacks, salt generation, work factor tuning |
| CSRF protection | Framework built-in (gorilla/csrf, Django CSRF) | Token generation, double-submit cookie pattern complexity |
**Concurrency**:
| Problem | Library | Why Not DIY |
|---------|---------|-------------|
| Rate limiting | uber-go/ratelimit, token-bucket | Token bucket correctness under concurrency, clock drift |
| Connection pooling | database/sql, pgxpool | Leak detection, health checking, graceful degradation |
| Worker pool | gammazero/workerpool, concurrent.futures | Panic recovery, graceful shutdown, backpressure |
The researcher should populate this table with domain-specific entries based on the actual technology being researched, not just copy the examples above.
---
## Anti-Features Output Section
Research output includes a mandatory section listing features to explicitly NOT build, with rationale. Why? Explicitly naming what is out of scope is as valuable as naming what is in scope. Without this, scope creep happens through "while we're at it" additions that seem reasonable in isolation but compound into over-engineering.
### Format
Every research deliverable MUST include this section:
```markdown
## Anti-Features
Features to explicitly NOT build:
| Feature | Rationale |
|---------|-----------|
| [Feature that might seem useful] | [Why building it would be a mistake] |
```
### Common Anti-Feature Categories
- **Build vs. Buy**: "Custom auth system" — Use OAuth2 provider; auth is a liability, not a differentiator
- **Premature Abstraction**: "Plugin system" — No current need for extensibility; add when 3+ real use cases emerge
- **Complexity Without Demand**: "GraphQL API" — REST covers all current use cases; GraphQL adds complexity without user demand
- **Scope Creep**: "Admin dashboard" — CLI tooling covers current admin needs; UI adds maintenance burden without proportional value
- **Future-Proofing**: "Multi-region support" — Single region serves current scale; premature distribution adds latency debugging complexity
The researcher should identify anti-features specific to the domain being researched, not generic ones. Ask: "What will someone inevitably suggest adding that we should preemptively say no to?"
---
## Blocker Criteria
STOP and ask the pipeline orchestrator (`pipeline-orchestrator.md`) (wait for explicit confirmation) when:
| Situation | Why Stop | Ask This |
|-----------|----------|----------|
| Only 1 subdomain discovered | Domain may not need decomposition | "Only 1 subdomain found. Proceed as single pipeline or broaden scope?" |
| 8+ subdomains discovered | May be over-splitting | "Found {N} subdomains — should I merge related ones or keep all?" |
| Existing skill reference covers 90%+ of domain with existing skills | May not need new pipelines at all | "Existing components cover nearly everything. What specifically is missing?" |
| No existing reference AND domain is well-established | Surprising — may indicate search failure | "Found no existing skill reference for {domain}. Verify this is correct before creating a new one?" |
| Two subdomains have identical preliminary chains | May be duplicates that should merge | "{Sub A} and {Sub B} have the same chain. Merge them?" |
### Always Confirm Before Acting On
- Whether to write a new domain reference vs. bind an existing one (always check inventory first)
- How many subdomains a domain should have (discover through research, let data drive the count)
- Which operator profile to apply (detect from context or use default)
- Whether a subdomain is too narrow or too broad (ask when uncertain)
---
## References
- [Task Type Guide](references/task-type-guide.md) - Detailed task type definitions with canonical chains and examples (loaded in Phase 2)
- [Pipeline Scaffolder](../pipeline-scaffolder/SKILL.md) - Downstream skill that consumes the Component Manifest to build pipeline components
- [Step Menu](../pipeline-scaffolder/references/step-menu.md) - Complete step inventory with output schemas and type compatibility (loaded in Phases 1 and 3)
- [Auto-Pipeline](../auto-pipeline/SKILL.md) - Downstream auto-pipeline system that consumes classified task types
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |