task-intelligence

## Overview

Pre-Task Intelligence Protocol — activates ALL relevant ecosystem agents BEFORE executing any task the user requests. Enriches the context with parallel multi-agent analysis, produces a real time estimate (start→finish), maps likely and unlikely problems, and formulates an anticipatory execution plan with contingency strategies.

## When to Use This Skill

- When the user mentions "pre-task briefing" or related topics
- When the user mentions "task briefing" or related topics
- When the user mentions "task execution plan" or related topics
- When the user mentions "analyze before executing" or related topics
- When the user mentions "task intelligence" or related topics
- When the user mentions "consult agents in parallel" or related topics

## Do Not Use This Skill When

- The task is unrelated to task intelligence
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

Before any execution, this agent performs a **complete intelligent briefing**:

1. **Activates all relevant agents in parallel** — each analyzes the task through its own lens
2. **Synthesizes the collective knowledge** into a unified plan
3. **Estimates real time** from start to finish (with a per-step breakdown)
4. **Maps likely problems** and resolves them ahead of time
5. **Defines checkpoints** to detect deviations before they become blockers

The core reason: executing a task without this briefing is like operating without a pre-op exam.
Spending 30-60 seconds on parallel analysis eliminates hours of rework.

---

## Phase 1 — Task Classification (5-10 Seconds)

First of all, classify the task into one of the categories:

| Category | Examples | Briefing Level |
|-----------|---------|-------------------|
| **Simple** | answer a question, explain a concept, small edit | Minimal (scan only) |
| **Moderate** | create a file, modify a skill, install a dependency | Normal (scan + match + estimate) |
| **Complex** | create a new skill, API integration, architecture, refactoring | Full (all steps below) |
| **Critical** | irreversible actions, deploys, delete, reset, modify infra | Maximum + explicit confirmation |

For **Simple** tasks, execute normally without a full briefing.
For **Moderate**, **Complex** and **Critical**, run the full protocol below.

---

## Phase 2 — Parallel Scan And Match

Run simultaneously:

```bash

## Terminal 1 — Update The Registry

python agent-orchestrator/scripts/scan_registry.py

## Terminal 2 — Identify Relevant Agents

python agent-orchestrator/scripts/match_skills.py "<user's task>"
```

If `matched >= 2`, run orchestration:
```bash
python agent-orchestrator/scripts/orchestrate.py --skills <skill1,skill2,...> --query "<task>"
```

---

## Phase 3 — Briefing The Specialized Agents

For each relevant agent identified in the match, ask a targeted question:

**Consultation pattern by agent type:**

- **007 (Security)**: "Does this task have attack vectors, exposed data, or irreversible actions?"
- **skill-sentinel (Quality)**: "Is there a redundant skill? Does the skill to be created/modified follow the standards?"
- **agent-orchestrator (Orchestration)**: "Which existing skills already solve part of this task?"
- **matematico-tao (Complexity)**: "What is the computational complexity? Are there non-obvious optimizations?"
- **context-guardian (Continuity)**: "Is there context from previous sessions relevant to this task?"
- **advogado-especialista/criminal (Legal)**: "Are there legal implications, LGPD, or regulatory risks?"
- **leiloeiro-ia (Auctions)**: "Does this task involve data or logic from the auction domain?"

Do not consult every agent blindly — pick the **3-5 most relevant** ones for the task.

---

## Phase 4 — Real Time Estimate

Build an honest time breakdown based on the real complexity:

```
TIME ESTIMATE — [Task Name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Step 1: [name]           ~X min   [reason for the time]
Step 2: [name]           ~X min   [reason for the time]
Step 3: [name]           ~X min   [reason for the time]
Contingency (problems)  +X min   [buffer for typical surprises]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
TOTAL ESTIMATED:         ~X min
Confidence: High/Medium/Low — [justification]
```

**Rules for an honest estimate:**
- Never underestimate to please — the user needs to know the real time
- Always add a 20-30% buffer for typical problems
- If confidence is Low, explain why and what would raise it
- Distinguish "agent execution time" vs. "user waiting time"

---

## Phase 5 — Problem Map (Proactive Anticipation)

Think in THREE layers of problems:

#### Likely Problems (80%+ chance of happening)
These are the problems that ALWAYS happen. Resolve them BEFORE you start.

Examples by category:
- **New skills**: invalid YAML → validate with `python -c "import yaml; yaml.safe_load(open('SKILL.md').read())"` before installing
- **External APIs**: expired key, rate limit, endpoint change → check authentication first
- **Installations**: missing dependencies, incompatible version → read requirements.txt before running
- **Files**: path doesn't exist, permission denied, wrong encoding → check before opening
- **Git/Versioning**: wrong branch, merge conflict, uncommitted changes → always `git status` first

#### Possible Problems (30-70% chance)
Problems that may happen depending on the current state.

Strategy: quickly check the state before assuming it's OK.

#### Unlikely but Critical Problems (< 10% but high impact)
Irreversible actions, data loss, credential exposure.

Strategy: preventive backup, explicit confirmation, rollback plan.

**Problem-map template:**

```
PROBLEM MAP — [Task Name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LIKELY (resolve before starting):
  ⚠ [problem] → [preventive fix applied now]
  ⚠ [problem] → [preventive fix applied now]

POSSIBLE (monitor during execution):
  ~ [problem] → [warning sign] → [action if it occurs]

CRITICAL (low prob, high impact):
  🔴 [risk] → [backup/rollback plan]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Phase 6 — Enriched Execution Plan

After gathering the agents' analyses + estimates + problem map, produce:

```
PRE-EXECUTION BRIEFING — [Task Name]
════════════════════════════════════════════
CONTEXT GATHERED:
  • [insight from agent 1]
  • [insight from agent 2]
  • [insight from agent 3]

EXECUTION PLAN:
  1. [step] (~Xmin) — [why this order]
  2. [step] (~Xmin) — [dependency on the previous step]
  3. [step] (~Xmin) — [quality check]

TOTAL TIME: ~Xmin | CONFIDENCE: High/Medium/Low

PRE-RESOLVED PROBLEMS:
  ✅ [problem] → [applied fix]
  ✅ [problem] → [applied fix]

CHECKPOINTS:
  [ ] After step 1: verify [success criterion]
  [ ] After step 2: verify [success criterion]
  [ ] Final: validate the complete result

ROLLBACK PLAN (if something goes wrong):
  → [how to undo each critical step]
════════════════════════════════════════════
```

---

## Integration With The Ecosystem

This agent **complements** agent-orchestrator — it does not replace it:

- **agent-orchestrator**: identifies WHICH skills to use (routing)
- **task-intelligence**: enriches HOW to use them + when + with what risks (briefing)

Both should be activated together. CLAUDE.md already requires the orchestrator — this agent adds the intelligence layer on top of it.

---

## When Not To Use The Full Briefing

- Quick one-line questions (answering directly is more efficient)
- Pure read tasks (read, grep, glob without side effects)
- Simple iterations within an already-planned task
- When the user asks to "just answer quickly" / "go with the flow"

The goal isn't bureaucracy — it's intelligence in service of real speed.

---

## References

- `references/problem-catalog.md` — Catalog of typical problems by domain
- `references/time-patterns.md` — Historical time patterns by task type
- `scripts/pre_task_check.py` — Automated pre-task check script

---

## Example Of A Complete Briefing

**User's task:** "Create a skill for Stripe integration"

```
PRE-EXECUTION BRIEFING — Skill: stripe-integration
════════════════════════════════════════════════════

CONTEXT GATHERED (3 agents consulted):
  • 007: CRITICAL — Stripe API keys must NOT go into SKILL.md or git.
    Use environment variables (.env). Webhooks need HMAC-SHA256 validation.
  • skill-sentinel: whatsapp-cloud-api already implements the HMAC-SHA256 pattern for webhooks
    — reuse that pattern. Skill should follow the structure: config.py + client.py + SKILL.md.
  • agent-orchestrator: 3 similar skills (whatsapp, telegram, instagram) as architecture
    references. None conflicts with Stripe.

EXECUTION PLAN:
  1. Create the directory structure (~2min) — base for the other files
  2. Write SKILL.md with the workflow (~5min) — defines the agent's behavior
  3. Create config.py with environment variables (~3min) — no hardcoded keys
  4. Create stripe_client.py with authentication (~10min) — main methods
  5. Create webhook_handler.py with HMAC-SHA256 (~5min) — reuse the whatsapp pattern
  6. Install via skill-installer (~2min) — validation + registration
  7. Generate a ZIP (~1min) — for backup/manual upload

TOTAL TIME: ~28min | CONFIDENCE: High
(clear structure, known dependencies, no uncertain external APIs)

PRE-RESOLVED PROBLEMS:
  ✅ Exposed API key → .env mandatory, .gitignore configured
  ✅ Invalid YAML → validate before installing
  ✅ Webhook without authentication → HMAC-SHA256 included in the plan

CHECKPOINTS:
  [ ] After SKILL.md: yaml.safe_load raises no exception
  [ ] After config.py: no hardcoded credential strings
  [ ] Final: skill-installer validates all 10 checks

ROLLBACK PLAN:
  → If skill-installer fails: folder in /tmp/stripe-skill-backup/
  → If the ZIP is corrupted: rebuild with build_ecosystem.py
════════════════════════════════════════════════════
```

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `agent-orchestrator` - Complementary skill for enhanced analysis
- `multi-advisor` - Complementary skill for enhanced analysis