Build a useful promplet step by step.

0. Setup

Work from the WeaveMark repository root. The commands below assume the package is installed in editable mode and the weavemark command is available on your path.

cd weavemark
pip install -e ".[dev]"
weavemark --help

Create a scratch directory for this tutorial. It keeps generated files separate from the existing examples.

mkdir -p outputs/tutorial-investment
mkdir -p outputs/tutorial-investment/prompts

Completed example

This tutorial teaches by building from scratch, but the completed prompt is checked in as a normal public spec: promplets/catalog/standalone/investment-brief.weavemark.md.

weavemark library builtin:catalog/standalone/investment-brief \
  --var ticker=MSFT \
  --var audience="investment committee" \
  --var time_horizon="3 years" \
  --var source_notes="Paste your source notes here." \
  --var depth=committee \
  --var include_watchlist=true \
  --batch-only \
  --output outputs/tutorial-investment/compiled-prompt.md

1. Write the first spec

Start with one readable Markdown prompt. The only WeaveMark pieces are the version pragma, variables, an output contract, and deterministic assertions. This is a runnable reduction of the checked-in investment brief; later steps add the omitted refinements and branches. Save it as outputs/tutorial-investment/investment-brief.weavemark.md.

@promplet version: 0.7

# Investment brief

Write in a clear, sober, evidence-oriented style. Avoid hype, unsupported
certainty, and investment advice phrased as instructions to buy, sell, or hold.

Write an educational investment brief for @{ticker}.

Audience: @{audience}

Time horizon: @{time_horizon}

Use the following notes as source material:

@{source_notes}

@output enforce: strict
  Return exactly these sections:
  1. Thesis
  2. Evidence
  3. Risks
  4. Alternatives
  5. Open questions
  6. Decision trigger
  End with the exact sentence: "This is educational analysis, not financial advice."

@assert contains: "Risks"
@assert contains: "Open questions"
@assert contains: "not financial advice"

2. Add the reusable analysis lenses

Now make the investment brief more credible without pasting a giant checklist into the local source. Add these @refine lines directly below the version pragma.

@refine module:weavemark.std.reasoning.base_analyst
@refine module:weavemark.domains.finance.finance_safety mingle: true
@refine module:weavemark.std.guidelines.evidence_quality mingle: true
@refine module:weavemark.std.lenses.comparative_alternatives mingle: true
@refine module:weavemark.std.lenses.explainability mingle: true

After this change, your local file still reads like a brief, but the compiled prompt can carry finance safety, evidence discipline, and decision framing.

@promplet version: 0.7
@refine module:weavemark.std.reasoning.base_analyst
@refine module:weavemark.domains.finance.finance_safety mingle: true
@refine module:weavemark.std.guidelines.evidence_quality mingle: true
@refine module:weavemark.std.lenses.comparative_alternatives mingle: true
@refine module:weavemark.std.lenses.explainability mingle: true

# Investment brief

3. Compose the first artifact

Now provide values and ask WeaveMark to compose the final prompt. Use --batch-only for scripts, CI, and reproducible agent workflows.

weavemark outputs/tutorial-investment/investment-brief.weavemark.md \
  --batch-only \
  --var ticker=NVDA \
  --var audience="portfolio committee" \
  --var time_horizon="12 months" \
  --var source_notes="Revenue growth is strong, margins are elevated, valuation risk is material." \
  --var depth=committee \
  --var include_watchlist=true \
  --output outputs/tutorial-investment/brief.md

Open outputs/tutorial-investment/brief.md. The output should be a clean prompt with variables substituted, authoring directives removed, and the semantic constraints preserved as downstream instructions.

4. Add controlled variation with branching

Real prompts often need variants: executive summary vs. deep memo, conservative vs. aggressive analysis, with or without valuation tables. Add that variation in the spec instead of duplicating files.

@match depth
  "committee" ==>
    Keep the memo concise. Focus on decision relevance, downside, evidence
    quality, timing, and the smallest useful next research step.

  "deep" ==>
    Add detailed sections for unit economics, competitive dynamics, management
    quality, valuation sensitivity, and disconfirming evidence.

@if include_watchlist
  Add a watchlist table with:
  - metric
  - current reading
  - threshold that would change the assessment
  - evidence needed next

Compose again with --var depth=deep or --var depth=committee, and toggle include_watchlist. The output is still a pastable prompt, but now the source cleanly controls which analysis variant the assistant should perform.

Final step: Use the output

The tutorial output is a compiled prompt, not the finished investment analysis. WeaveMark has assembled the instruction; a downstream assistant still has to carry it out.

What you learned

• Use Markdown as the primary authoring surface.
• Use @{variables} for caller-provided inputs.
• Borrow reusable lenses with @refine instead of pasting checklists.
• Use @match and @if for controlled variation.
• Lock the output shape with @output and guard it with @assert.