The semantic toolbox: directives that reshape meaning.

Prompts as specifications

Most WeaveMark directives are semantic: their body is a sub-spec, and the WeaveMark Processor rewrites that sub-spec according to an instruction expressed in natural language. The result is compiled into the surrounding prompt — the directive itself never appears in the output.

Because the transformation understands meaning, you can refactor a prompt the way you refactor a program: extract obligations, normalize terminology, revise for neutrality, elaborate a concept, or enforce an output contract. The tour below draws every example from a real spec under promplets/.

Compose & reuse — @refine

@refine weaves a reusable promplet into the current one. With mingle: true (the default) it is specification refinement: the compiled result must imply the imported spec, but reads as one concrete document — not pasted fragments.

@refine module:weavemark.std.guidelines.prompt_quality mingle: true
@refine module:weavemark.std.reasoning.prompt_refinement_core mingle: true

# Prompt refactoring pipeline

From prompt-refactoring-pipeline.weavemark.md.

Elaborate a concept — @expand

@expand takes a specific, compact idea in its body and elaborates it into fuller prompt content the rest of the spec then builds on. It is not a way to inflate a one-liner into an entire specification — it makes one requirement or concept operational.

@expand mode: intention length: 70%
  Make the steel-manning requirement operational: each perspective must
  restate the strongest opposing position in a form its holder would endorse.

Here the steel-manning concept is expanded into a concrete obligation; later sections of the debate prompt refer back to it. mode is definition, intention, or context; length and focus tune the elaboration.

From multi-persona-debate.weavemark.md.

Transform meaning — @revise, @normalize

@normalize makes a body consistent. With scope: syntactic it harmonizes headings, lists, and terminology; with scope: semantic it resolves cross-references and contradictions.

@normalize "Resolve cross-references and contradictions while preserving intent." scope: semantic
  Requirements inventory:
  @extract "All hard requirements and output-format constraints." format: bullets
    @{raw_prompt}

  Draft to normalize:
  @normalize "Normalize headings, lists, and terminology without changing meaning." scope: syntactic
    @{raw_prompt}

@revise edits a body against an instruction — surgically adding or removing requirements while preserving the rest.

@revise "Remove standalone format labels such as `json` or `markdown`; describe JSON fields as a table instead." mode: editorial
  @{raw_prompt}

From prompt-refactoring-pipeline.weavemark.md.

Condense — @extract, @summarize, @compress

These derive tighter content from a body. @extract pulls out requested information (like extracting an interface); @summarize condenses; @compress forces brevity while preserving hard requirements.

@extract "key_concepts"
  From the topic "@{topic}", identify the 3–5 most important concepts.

@summarize
  Compare @{topic} against its main alternatives:
  @{alternatives}

@compress "Keep the migration guide concise while preserving checklist, rollback, and validation details."
  Provide a step-by-step migration guide from @{migration_from} to @{topic}.

From knowledge-base-article.weavemark.md.

Presentation — @style, @polish

@style imposes a voice or register on its body without changing the substance.

@style "Warm, precise, and Socratic. Ask before explaining. Never shame the learner."
  Teach @{topic} to @{learner_context}.

@polish is a final presentation pass: it unifies structure and smooths transitions without adding or removing substantive information. It requires a non-empty indented target body; a bodyless call is an error.

@polish "Harmonize the fully transformed prompt into one coherent final prompt without adding or removing requirements."
  @revise "Remove standalone format labels such as `json`, `text`, or `markdown`." mode: editorial
    ...

From adaptive-tutor.weavemark.md and prompt-refactoring-pipeline.weavemark.md.

Examples — @generate_examples

@generate_examples produces worked examples consistent with its body — useful for turning an abstract contract into something an assistant can imitate.

@generate_examples count: 2
  Generate realistic request/response examples for each endpoint above.

From api-docs-generator.weavemark.md.

Clarify & improve — @ask, @iterate

@ask pauses compilation to gather missing human context before continuing with its body. @iterate compiles a body through explicit steps, judges the result, and reruns steps that can be materially improved. They compose: a leading @ask is the iteration target.

@iterate 3
  @ask clarifying question detail_level: 35%
    @expand mode: intention
      Draft a prompt for the first-run onboarding flow for @{product}.

From iterative-onboarding-prompt.weavemark.md.

Contracts — @output, @assert, @structural_constraints

These make the shape of the result checkable. @structural_constraints declares required sections; @assert states invariants with a severity; @output pins the final response format.

@structural_constraints strict: true
  Required sections in order:
  1. Role and Identity
  2. Core Requirements
  3. Constraints and Prohibitions
  4. Output Format

@output enforce: strict
  The refactored prompt must be ready to use as-is with an LLM.
  Resolve cross-references and contradictory instructions.
  Specify what to do when input is ambiguous.

@assert contains: "Resolve cross-references and contradictory instructions."
@assert contains: "Specify what to do when input is ambiguous." severity: warning

From prompt-refactoring-pipeline.weavemark.md.

A full pipeline

Put together, these directives refactor a messy prompt the way a compiler pass refactors a program. The checked-in prompt-refactoring-pipeline.weavemark.md extracts obligations, resolves contradictions, revises wording, enforces structure, and polishes the whole. The transformation directives are nested so the raw prompt flows through the passes one by one:

@refine module:weavemark.std.guidelines.prompt_quality mingle: true
@refine module:weavemark.std.reasoning.prompt_refinement_core mingle: true

# Prompt refactoring pipeline

@polish "Harmonize the fully transformed prompt into one coherent final prompt without adding or removing requirements."
  @revise "Remove standalone format labels such as `json`, `text`, or `markdown`; describe JSON fields as bullets or a table instead." mode: editorial
    @structural_constraints strict: true
      Required sections in order:
      1. Role and Identity
      2. Core Requirements
      3. Constraints and Prohibitions
      4. Output Format

      @revise "If a Removal instruction block appears after the draft, apply it to the draft." mode: editorial
        @revise "If an Additional section block appears after the draft, integrate it into the draft." mode: editorial
          @revise "@{revision_instruction}" mode: editorial
            @normalize "Resolve cross-references and contradictions while preserving intent." scope: semantic
              Requirements inventory:
              @extract "All hard requirements and output-format constraints." format: bullets
                @{raw_prompt}

              Draft to normalize:
              @normalize "Normalize headings, lists, and terminology without changing meaning." scope: syntactic
                @{raw_prompt}

Create a deliberately rough input prompt so the pipeline has something concrete to improve:

mkdir -p outputs/tutorial-directives
cat > outputs/tutorial-directives/messy-prompt.md <<'PROMPT'
Write an onboarding guide. Keep it short but explain every internal detail.
Use a friendly tone. Never ask questions. If requirements are ambiguous,
ask one clarifying question before proceeding. Return Markdown.
PROMPT

weavemark library builtin:catalog/standalone/prompt-refactoring-pipeline \
  --var raw_prompt="$(cat outputs/tutorial-directives/messy-prompt.md)" \
  --var revision_instruction="Add a section on handling ambiguous input." \
            --var add_section=true \
            --var new_section_content="Handling ambiguous input: ask one focused clarifying question before proceeding." \
            --var remove_section=false \
            --var contraction_instruction="Preserve every required section." \
            --batch-only \
            --output outputs/tutorial-directives/refactored-prompt.md

Final step: Use the output

The pipeline output is the cleaned prompt. It is not the onboarding guide requested by the rough input; it is the improved instruction you now send onward.

What you learned

• @refine composes reusable promplets by specification refinement.
• @expand elaborates a specific concept the rest of the spec builds on.
• @revise and @normalize transform meaning — surgically or for consistency.
• @extract, @summarize, and @compress condense without dropping hard requirements.
• @style and @polish shape voice and presentation without changing substance.
• @generate_examples turns a contract into worked examples.
• @ask and @iterate gather context and improve results step by step.
• @output, @assert, and @structural_constraints make the result checkable.