Task Brief

Converts vague instructions into a structured, executable specification. Prevents costly rework and wrong assumptions before implementation begins.

1. Purpose

Define what needs to be built or solved before taking action. A "Task Brief" is a written summary that freezes scope, lists required inputs, states deliverables, and provides binary pass/fail acceptance tests.

2. When to Use

Use this skill whenever:

• A user request is broad, ambiguous, or lacks explicit constraints.
• Starting a multi-step engineering task that touches critical files.
• Handoff from a user prompt into a multi-agent or multi-step execution pipeline.

3. When Not to Use

• If the request already contains exact, unambiguous file paths, commands, and success criteria: proceed directly to execution.
• If the task is purely answering a simple factual question: answer directly.
• To break an already-clear task into ordered execution steps: use step-decomposer instead.

4. Required Inputs

• raw_request: The original user prompt or issue description (string).
• project_context: Available repository files, tech stack, or environment details (optional string).

5. Missing-Input Behavior

1. If raw_request is completely empty or blank:
   • Stop immediately.
   • Reply: "Error: No request provided. Please state what task you want to accomplish."
2. If raw_request refers to an unknown file or system (e.g., "Fix the login bug" but no auth system exists):
   • Check local workspace files first.
   • If still missing after 1 inspection step: list the exact ambiguity and ask the user to clarify. Do not guess the target file.

6. Procedure

Follow these numbered actions:

1. Action 1: Extract Core Intent
   • Identify the user's ultimate goal in one sentence.
   • Classify task type: Bug Fix, Feature, Refactor, Documentation, or Operations.
2. Action 2: Identify In-Scope vs Out-of-Scope Work
   • List at most 4 strictly required changes (In-Scope).
   • List at least 2 common assumptions that are explicitly forbidden or deferred (Out-of-Scope).
3. Action 3: Define Required Artifacts
   • List exact target files or directories to create, modify, or delete.
4. Action 4: Define Objective Acceptance Criteria
   • Write 2 to 5 verifiable, binary criteria (e.g., "Command X exits with code 0", "Function Y returns schema Z").
5. Action 5: Emit Task Brief
   • Format the brief according to Section 8.

7. Decision Rules

• If the request asks for "fast", "clean", or "modern" without metrics: translate to concrete standard practices (e.g., passes linter, zero warnings).
• If the request includes destructive operations (deleting data, drop table, rm -rf): mark as Risk Level: High and require explicit user approval.
• If dependencies or prerequisites are missing from the project: add them to "Prerequisites Needed" before marking the brief ready.

8. Output Format

Always format the task brief using this template:

### Task Brief: [Concise Task Title]

- **Classification**: [Bug Fix | Feature | Refactor | Documentation | Operations]
- **Risk Level**: [Low | Medium | High]
- **Target Files**: [List of relative paths or TBD]

#### Objective
[One clear sentence stating the end state.]

#### Scope Boundaries
- **In-Scope**:
  - [Item 1]
  - [Item 2]
- **Out-of-Scope**:
  - [Excluded item 1]
  - [Excluded item 2]

#### Acceptance Criteria
- [ ] Criterion 1 (Must be verifiable by test, command, or exact inspection)
- [ ] Criterion 2

#### Open Questions / Blockers (if any)
- [None, or specific blocking question]

9. Verification Checklist

Before delivering the brief, check every box:

• The objective is a single unambiguous sentence.
• At least one item is marked out-of-scope to prevent scope creep.
• Every acceptance criterion can be tested objectively.
• No internal chain-of-thought or reasoning traces are leaked into the output.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• The user request has contradictory requirements that cannot both be satisfied.
• The request requires credentials, secrets, or paid external APIs not configured in the workspace.
• The user request asks to perform actions outside the project repository.

12. Examples

Example 1: Successful Execution

Input:

User request: "Make our CLI command output prettier and add json support."
Context: CLI built in Node.js, uses Commander.js.

Expected Observable Actions:

1. Identified CLI package and entry file.
2. Formulated structured brief separating aesthetic output from JSON formatting flag.

Output:

### Task Brief: Add JSON Output Flag to CLI

- **Classification**: Feature
- **Risk Level**: Low
- **Target Files**: `src/cli.js`, `tests/cli.test.js`

#### Objective
Add an optional `--json` flag to the CLI command so output can be parsed programmatically while keeping standard human-readable text by default.

#### Scope Boundaries
- **In-Scope**:
  - Add `--json` flag to command options in `src/cli.js`.
  - Format successful results as single-line JSON string when flag is present.
  - Add unit test verifying valid JSON output.
- **Out-of-Scope**:
  - Re-styling human-readable color themes or adding new third-party chalk dependencies.
  - Modifying error exit code semantics.

#### Acceptance Criteria
- [ ] Running `cli-tool --json` prints valid JSON to stdout and exits with code 0.
- [ ] Running `cli-tool` without `--json` preserves existing human-readable output.
- [ ] `npm test` passes with new test case included.

#### Open Questions / Blockers
- None. Ready for step decomposition.

Example 2: Ambiguous or Missing Input

Input:

User request: "Fix it, it crashed."

Output:

### Task Brief: Clarification Needed for Reported Crash

- **Classification**: Bug Fix
- **Risk Level**: High (Unknown scope)
- **Target Files**: TBD

#### Objective
Resolve the runtime crash once reproduction details are provided.

#### Scope Boundaries
- **In-Scope**: TBD
- **Out-of-Scope**: TBD

#### Acceptance Criteria
- [ ] Crash reproduction step is identified.
- [ ] Fix passes regression test.

#### Open Questions / Blockers
- **Blocking Question**: Please provide the exact command executed, the full error message or stack trace, and the expected behavior.

Example 3: Expected Final Output

Output:

### Task Brief: Add CSV Export to User Table

- **Classification**: Feature
- **Risk Level**: Low
- **Target Files**: `src/users/export.ts`, `src/routes/users.ts`

#### Objective
Provide an endpoint `GET /api/users/export?format=csv` that streams active user records in RFC 4180 CSV format.

#### Scope Boundaries
- **In-Scope**:
  - Generate CSV with columns: `id`, `email`, `created_at`.
  - Escape comma, quote, and newline characters per RFC 4180.
- **Out-of-Scope**:
  - Exporting password hashes, tokens, or deleted users.
  - Excel (.xlsx) formatting.

#### Acceptance Criteria
- [ ] `curl -s "http://localhost:3000/api/users/export?format=csv"` returns HTTP 200 with `Content-Type: text/csv`.
- [ ] Header row matches `id,email,created_at`.
- [ ] Automated integration test in `tests/export.test.ts` passes.

#### Open Questions / Blockers
- None.