Writing Instruction Builder

---
name: writing-instruction-builder
description: Compose a writing instruction from voice, tone, style, and format entries you have already chosen. Returns a ready-to-paste LLM prompt prefix.
when_to_use: Use when the user names specific catalog entry ids, or has already picked them in this session. If the user describes a writing situation but does not know which entries fit, use entry-recommender instead; if they want to save or reuse a personal default style, use style-profile.
metadata:
  version: "0.3.0"
---

# Compose Writing Instruction

Compose a writing instruction by combining taxonomy entries from the Voice and Tone, Style, and Format axes.

## Usage

```
/writing-style-catalog:writing-instruction-builder [voice=<id>] [tone=<id>] [style=<id>] [format=<id>] [topic=<text>] [audience=<text>]
```

All parameters are optional. If omitted, the skill picks sensible defaults.

## Parameters

- `voice` - Voice entry ID (e.g., `pragmatic-architect`, `pastoral`, `columnist`)
- `tone` - Tone entry ID (e.g., `candid`, `warm`, `matter-of-fact`)
- `style` - Style entry ID (e.g., `problem-solution`, `devotional-reflection`)
- `format` - Format entry ID (e.g., `adr`, `blog-post-long-form`, `slack-message`)
- `topic` - The topic or subject to write about (optional, for a more concrete composed instruction)
- `audience` - The intended audience (optional, defaults to general)

### Safety note for `topic` and `audience`

Both are free text that lands in two sensitive places: the shell command (if you build one) and the composed instruction itself (they are appended verbatim, and the composed instruction becomes prompt material downstream). Shell-quote them properly when constructing a command - an ordinary apostrophe breaks naive quoting. Do not pass externally-sourced or untrusted text through bare `--topic`/`--audience` arguments: compose without them and append that text yourself with a non-shell tool, mirroring the temp-file discipline `entry-recommender` uses for situation text.

## What the Skill Does

1. Validates each provided entry ID against the taxonomy catalog
2. Reads the `llm_instruction_phrasing` from each matching entry
3. Assembles a composed instruction string in a fixed precedence order: voice, then tone, then style, then format
4. Checks the selected entries against each other's relationship fields and warns on any conflict (without blocking)
5. Returns the composed instruction ready to paste into any LLM prompt

### Implementation

The composition is implemented by the helper script `scripts/build-instruction.py` in this
skill folder. It reads the catalog from the `taxonomy/` directory at the plugin root, so that
directory ships with the plugin. The slash command takes `key=value` arguments; the script
itself takes `--flag value` arguments. Run it directly to compose without the slash command,
for example:

```bash
python "${CLAUDE_SKILL_DIR}/scripts/build-instruction.py" --voice pragmatic-architect --tone candid --format adr
```

(From a plain repo checkout without the plugin loaded, the equivalent is `python skills/writing-instruction-builder/scripts/build-instruction.py ...` run from the repo root.)

### Conflict-aware composition

The builder reads each selected entry's `avoid_with` and `pairs_well_with` relationships and
reports on them, so a composition is a checked guarantee rather than a blind concatenation. The
rules (see ADR 0016):

- **Conflicts are symmetric.** A pair is flagged if *either* entry lists the other in
  `avoid_with`, so the warning never depends on which author recorded the link.
- **Warn, never block.** A conflicting pair still composes (you may want a deliberate tension);
  the builder emits a warning and applies voice -> tone -> style -> format precedence so the
  higher-precedence axis leads.
- **Affirmations.** A `pairs_well_with` match is surfaced as a confirming note.

The composed instruction prints to stdout; conflict warnings and affirmation notes print to
stderr, so stdout stays a clean, pipeable prompt. For example, pairing the
`pragmatic-architect` voice with the `reverent` tone (which it lists in `avoid_with`) still
returns the instruction and prints:

```
warning: conflict - pragmatic-architect (voice) and reverent (tone) are marked avoid_with.
Composing anyway with voice -> tone -> style -> format precedence; expect tension.
```

## Examples

Compose an ADR in pragmatic-architect voice with candid tone:

```
/writing-style-catalog:writing-instruction-builder voice=pragmatic-architect tone=candid format=adr
```

Compose a pastoral devotional:

```
/writing-style-catalog:writing-instruction-builder voice=pastoral tone=reverent style=devotional-reflection format=devotional-entry topic="The discipline of rest"
```

## Available Entries

Run without arguments to see all available entries grouped by axis.