plumbline-shape-engine

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Shape engine

## Outcome and completion

Shape product intent without implementing it. Establish the smallest useful
understanding of the destination, users, behavior, scope, non-goals, evidence,
open product questions, and fog. Complete Shape when the next safe phase is
clear or the one material product question is presented with a recommendation,
alternatives, tradeoff, and default.

Writing an explicitly approved transient shaping handoff is documentation, not
implementation. Read canonical repository docs, current code, tests, and
configuration for facts before asking anything. Read
`references/product-autonomy.md` and `references/research-policy.md` when the
task involves product decisions or external evidence.

## Classify before asking

Start with a targeted, read-only repository pass. Classify unresolved items as:

- repository facts, resolved from the repository;
- external capability or design questions, answered with bounded research;
- user-owned product decisions, asked one at a time;
- vague future uncertainty, parked as fog.

## Use a decision frontier

For broad shaping, keep a lightweight decision map in the working context. Map
material product decisions, the facts or research they depend on, and fog that
is not yet question-shaped. Do not create a durable decision-tree artifact
unless the user approves the existing shaping handoff.

The **decision frontier** is the set of material user-owned decisions whose
prerequisites are settled. Select the highest-leverage frontier question for
the next turn. Keep one question at a time, even when several frontier
questions are independent; this preserves the user's attention and Plumbline's
bounded conversation. Hold downstream questions until their prerequisites are
known. Recompute the frontier after a material answer, repository fact, or
research finding.

Research facts rather than asking the user for them. Independent factual
research may run in parallel when its questions and join condition are clear;
the main thread integrates the findings before selecting the next product
question. When the frontier is empty, or only fog and non-blocking residuals
remain, move to the next safe phase instead of manufacturing more questions.

For a material capability or design question whose options are not settled,
research before asking the user to choose. Do not make the user know which
tools, products, libraries, or patterns exist.

Use the matching project-local `researcher` for a bounded report-only brief
when available. Otherwise research directly on the main thread. Never use a
personal or global agent as fallback. Research
returns evidence to the main thread; it does not edit files, specifications,
plans, Git state, or the handoff, and it does not spawn children. Use one
researcher by default. Parallelize only independent questions with a stable
question set and a clear main-thread join.

Return a sufficient option landscape rather than an exhaustive catalog. For
each useful finding, provide the source, implication, recommendation, realistic
alternatives, tradeoffs, and remaining uncertainty. Use official documentation,
standards, or source repositories for current technical claims; use reputable
product or design sources for patterns; record versions or retrieval dates when
freshness matters. Stop once the evidence supports the next safe product
question.

Ask only questions whose answers change product behavior, scope, user
experience, privacy/security, destructive handling, compatibility, material
cost, or another difficult-to-reverse outcome. Resolve technical boundaries,
names, module placement, test seams, and implementation details from evidence,
conventions, and safe defaults. Use this question shape:

Ask one question or one bounded batch at a time.

1. recommendation;
2. realistic alternatives;
3. product tradeoff;
4. default if the user has no preference.

When the frontier contains numerous independent questions, use a small batch
instead of serial turns. A normal batch contains two to four questions; reduce
it when the decisions are high-consequence or cognitively dense, and expand it
only when the user asks for a larger pass. Keep each question independently
answerable and label the response mapping clearly:

❓ **Q1** - **<question title>**: <question body and realistic choices>
➡️ **Recommendation:** <recommended answer and why>

Include the tradeoff and default for each question. Wait for the user's batch
answers, accept partial answers, then recompute the decision frontier. Keep
dependent questions for a later batch and use one question when answering one
choice would change the meaning of another.

## Delegated architect escalation

When an architect working inside an active goal discovers a material product
question, return a structured escalation to the main orchestrator. Include the
affected checkpoint and overall objective, the plain-language question, why it
changes behavior or acceptance, recommendation, alternatives, tradeoff,
default, whether the checkpoint is blocked, and safe independent work.

The child returns the escalation; it does not ask the user directly, end the
goal, replace the plan, or start another lifecycle. The main orchestrator uses
the existing Shape conversation only when needed, preserves the active goal and
plan, and records the answer or residual uncertainty. Block only the affected
checkpoint when the answer is genuinely required; continue independent work
where possible.

## Optional prototype probe

After local facts and necessary research, decide whether the remaining
uncertainty is experiential rather than factual. Offer a throwaway prototype
only when a small runnable probe is likely to answer a material question faster
than another planning round. Keep the smallest useful form:

1. conversation, worked example, or state sketch;
2. in-memory logic, state, or data probe;
3. isolated UI or interaction variant.

From nickyfactz/plumbline, MIT.

More from nickyfactz/plumbline