execution-context-builder

name	execution-context-builder
description	Synthesizes the chosen (or only) candidate flow into the canonical execution-context Markdown + JSON artifacts under .claude/clarifications/. Activates after flow-detector returns a single candidate, or after flow-selector confirms the user's choice. Never asks follow-up questions.

Execution Context Builder

Take a full_context record and write the two canonical artifacts.

Activation Triggers

This skill activates when:

• flow-detector returned exactly one candidate (skip selector, come straight here).
• flow-selector has resolved the user's pick (or synthesized one from "Other").

This skill never asks the user a question. If the input full_context has missing fields, fill them with conservative defaults (see "Field Defaults" below) and move on.

Inputs

The skill receives:

• task — the original task description (string), and optionally a source ref (e.g., ENG-123).
• full_context — the chosen candidate's context record. Schema is defined in references/execution-context.json.

Process

1. Resolve the slug

Generate a slug from the task title:

• Lowercase, replace non-alphanumeric runs with -, strip leading/trailing -.
• Truncate to 60 characters max, on a word boundary.
• If the result is empty (no usable characters), fall back to clarification-YYYYMMDD-HHMMSS using the current local time.

Examples:

• "Send message on sign-in" → send-message-on-sign-in
• "Migrate auth to Better Auth (Phase 2)" → migrate-auth-to-better-auth-phase-2
• "!!!" → clarification-20260427-143022

2. Fill defaults

If any required field in full_context is missing, fill with these defaults:

Field	Default
trigger.timing	"after"
trigger.preconditions	[]
action.channel	"in-app"
flow.mode	"async"
flow.transport	null
failure_handling.strategy	"retry"
failure_handling.details	"3 attempts with exponential backoff, then log"
out_of_scope	[]

Defaults are not user-visible questions — silently apply them.

3. Build the JSON artifact

Read references/execution-context.json, populate it from full_context, add metadata:

{
  "task": { "title": "<original task>", "source": "<ticket ref or null>", "slug": "<slug>" },
  "entity": "...",
  "trigger": { "event": "...", "timing": "...", "preconditions": [...] },
  "action": { "verb": "...", "channel": "...", "recipient": "..." },
  "flow": { "services": [...], "mode": "...", "transport": "..." },
  "failure_handling": { "strategy": "...", "details": "..." },
  "out_of_scope": [...],
  "metadata": {
    "created_at": "<ISO-8601>",
    "created_by": "clarify@0.1.0"
  }
}

Validate the result parses with a JSON parser before writing. If parsing fails, fix and retry; never write malformed JSON.

4. Build the Markdown artifact

Read references/execution-context.md, fill the template from the same full_context. Keep it human-readable — the developer is the primary reader.

5. Write both files

Path: .claude/clarifications/<slug>.local.md and .local.json.

• Create the .claude/clarifications/ directory if it doesn't exist.
• If a file with the same slug already exists, refuse to overwrite. Print:

  A clarification already exists at .claude/clarifications/<slug>.local.md. Delete it first, or re-run /clarify with a different task title.

• Write atomically: write to a temp file, then rename. Prevents partial files on crash.

6. Optional cross-pack hooks (silent if absent)

After writing, if .claude/failure-log.local.md exists in the project, append a one-liner under "Pattern Mistakes":

- [<ISO-8601>] <slug> clarified — see .claude/clarifications/<slug>.local.md (kind: assumption-resolved)

If the failure-log file doesn't exist, skip silently. Do not create it.

7. Print the summary

✓ Execution context written:
  .claude/clarifications/<slug>.local.md
  .claude/clarifications/<slug>.local.json

Do not print the full content of either file. The developer opens the file to review.

Field Reference

See references/execution-context.md and references/execution-context.json for the canonical templates.

Anti-Patterns

Don't	Do Instead
Ask the user to fill in missing fields	Apply the defaults table silently
Overwrite an existing artifact	Refuse and tell the user to delete it
Write the JSON without parsing it first	Validate, then write
Print the full Markdown to chat	Print only the file path; the developer opens it
Create .claude/failure-log.local.md if it's missing	Skip the cross-pack hook silently

Success Criteria

• Both .local.md and .local.json files are written.
• JSON parses cleanly with a strict parser.
• Markdown contains every required section: Task, Entity, Trigger, Action, Flow, Failure handling, Out of scope, Metadata.
• Slug matches the rules in step 1.
• No question was asked during execution-context generation.
• Optional failure-log append is silent when the file is absent.