Trellis

View saved version →

---
name: learn-from-work
description: Learn reusable working methods from selected experience and propose handbook practices, checks, Playbooks, templates, or coordinated improvements. Use the current conversation, exact selected sessions, or explicitly supplied work evidence. Return editable Shape Handbook requests without writing files or applying proposals automatically. Do not use for research or analysis unrelated to working methods.
---

# Learn From Work

Before applying this skill, read the full [Trellis methodology](references/methodology.md).

Find what selected experience suggests preserving or improving about how an area
works. Recommend the form that serves the lesson; do not force every useful
distinction, check, or template into a Playbook. Learning produces proposals,
not handbook changes or automatic calls to Shape Handbook.

## Select the evidence

Use the current conversation by default, exact sessions selected by the user and
retrievable through the host, or explicitly selected work evidence such as artifacts
or an account of an episode. Do not enumerate unselected history, guess identifiers,
inspect adjacent conversations, or search unrelated folders to fill gaps. A selected
session does not authorize reading every file or service mentioned in it.

Report unavailable, ambiguous, or partial sources individually and continue with
usable evidence. State which sources you examined. If host limits require batches,
identify them rather than silently sampling or omitting sources. Reconstruct each
episode independently before comparing patterns. One source cannot establish what
an unavailable source contained.

When a handbook or surrounding area is selected, inspect relevant existing method
and shared guidance to judge fit and avoid duplication. Resolve workspace and area
from the request, project instructions, and README. A handbook is `<area>/handbook/`;
its parent owns the area. Its README may declare the workspace through:

```html
<!-- trellis:handbook {"format":1,"workspace":"../.."} -->
```

The path is relative to the handbook; a workspace-root handbook uses `..`. Verify
physical scope against the selected workspace, which need not be a Git repository.
Do not use the current directory, a marker, or symlinks to expand ambiguous scope.
Resolve multiple selected handbooks separately. Root and nested guidance can both
apply; ancestry does not settle conflicting rules. Avoid unrelated areas.

A destination need not be chosen before a useful proposal can be made. State any
unresolved handbook choice rather than inventing it. Ask only when the answer
materially changes the proposed method or its fit.

## Reconstruct before drawing lessons

Identify the starting situation, intended outcome, context, constraints, decisions
and cues, actions, results, verification, failures, and recovery relevant to the
proposed lesson. Distinguish direct observations, the user's account, stated intent,
and inference. An artifact records its contents; it does not establish an unobserved
process or prove that its author followed a particular method.

Look for useful turning points: a hidden constraint, correction, meaningful
distinction, failed approach, check that exposes an important distinction,
recurring difficulty, or recovery.
Prefer reasoning that would change future work over a chronology of tool calls.

An unfinished attempt can suggest a method without demonstrating its outcome.
Success does not establish which actions caused it or whether the method generalizes.
Consider another explanation, such as a reviewer's correction or a favorable input,
and a situation where the lesson would not help. Keep these interpretations distinct
from observed evidence; do not invent a counterexample or claim an unperformed
comparison. Current clarification can shape a proposal without rewriting the selected
evidence. Repetition alone does not turn a pattern into adopted policy.

When a missing fact or interpretation would change the lesso

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: shape-handbook
description: Create, adopt, review, or refine selected area handbooks, coordinating practices, checks, Playbooks, and templates. Use when the user asks to shape working methods or assess a handbook. Review requests stay read-only; ordinary work does not itself request handbook changes or Playbook creation.
---

# Shape Handbook

Before applying this skill, read the full [Trellis methodology](references/methodology.md).

Help the selected handbook improve a future contributor's decisions about the
area's work. Choose the smallest coherent change that serves the requested outcome;
the user need not divide a concern into separate practice, check, and template tasks.

## Follow the requested intent

A request to create, adopt, or refine a handbook authorizes the corresponding
changes. A review request asks for findings and remains read-only. If the user asks
for review and fixes, apply the requested fixes within scope. Do not require a
special invocation, a named mode, or repeated confirmation of existing authority.

Creating a Playbook requires a request to preserve that procedure, or the user's
acceptance of a proposal that clearly includes it. Broad improvement, a review
finding, or a learning recommendation alone does not authorize inventing Playbooks.
An intended procedure can be written without prior successful use; creating it
does not demonstrate its effectiveness or carry it out.

## Resolve the handbook and its owners

Resolve the workspace and owning area from the request and applicable project
instructions. A workspace is an identified working directory, not necessarily a
Git repository. Do not select the current directory when plausible alternatives
would materially change scope. Each handbook lives at `<area>/handbook/`; its
parent is the owning area and must be inside the selected workspace.
Verify that the workspace and owning area already exist as directories. Never
create their missing parents: every setup write must remain inside the handbook.

Read an existing README's single marker to check its declared workspace:

```html
<!-- trellis:handbook {"format":1,"workspace":"../.."} -->
```

The workspace path is relative to the handbook; use `..` for a workspace-root
handbook. Verify physical locations against the selected scope. The marker does
not grant authority over another workspace or ownership of every existing file.
Resolve each handbook separately in a multi-handbook request.

Inspect the requested area, applicable shared guidance, and explicitly selected
evidence. Do not search unrelated areas merely because they share a workspace.
Root and nested handbooks can both apply; ancestry alone does not settle conflicts.
Link shared rules at their owners, explain deliberate local specializations, and
raise consequential unresolved conflicts.

The handbook preserves how people do and review the work. Keep current plans,
drafts, decisions, and results in the area's working files. Judge mixed documents
statement by statement and link to the authoritative files for the work.
Extracting a practice does not authorize cleaning up its source outside the handbook.

## Resolve decisions before encoding them

Identify the future task or decision the requested change should help. Inspect the
selected sources first. Retrieve answers available there; ask the user about a
missing purpose, conflicting rule, acceptable tradeoff, or exception only when
different answers would change the guidance. Explain the concrete choice and its
consequence, offering grounded alternatives when useful. Do not ask the user to
design the handbook or choose artifact types.

Ask a small batch of consequential questions and wait for the answers before
encoding the dependent rules. Continue independent work where possible. Existing
instructions or explicit owner direction can settle a choice without another
confirmation. If the user cannot decide, keep that dependency visibly unresolved
or proposed; do not silently choose pol

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 12 — file references are metadata, not package contents.