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 lesson, ask a focused
question before finalizing that recommendation. Ground it in the selected episode:
what prompted a correction, which outcome mattered, what happened afterward, or
where the proposed method would not fit. Ask only questions whose plausible answers
would change the advice, and use answers already present in the sources. Do not
hand the analysis back as a generic reflection questionnaire.

Wait for the answer on that dependency while continuing supported independent
analysis. Use the reply to revise, narrow, or discard the candidate lesson, keeping
the user's present account distinct from inspected historical evidence. If the
answer is unknown or declined, state what remains tentative; do not keep asking
or convert uncertainty into a causal claim. Enough evidence needs no extra interview.

## Choose useful handbook improvements

Consider what would help a future contributor:

- **Practice:** a working distinction, convention, approach, or interpretation that
  changes recurring decisions.
- **Check:** an independently applicable expectation with concrete verification
  and meaningful outcomes.
- **Playbook:** a coherent repeatable task with a clear trigger, judgment, method,
  outcome, completion evidence, and meaningful recovery or stop conditions.
- **Template:** an adaptable structure or substantive prompts that improve
  repeated authoring.
- **Coordinated refinement:** an existing handbook concern that needs clearer
  ownership, links, scope, organization, or changes across several artifact types.

For a candidate lesson, identify a recognizable cue, the decision it would change,
why that change might help, its applicability and exceptions, and evidence that
could test it. Use these to assess usefulness, confidence, and maintenance cost;
they do not require separate headings. Prefer refining an existing owner when it
already covers the concern. Keep connected changes together and independently
useful proposals separate. Finding nothing worth preserving is a valid result.

Propose how to improve the working method while leaving the actual work in its
existing files. Judge mixed material statement by statement: a current task list,
result, or frequently consulted fact is not itself a reusable method. Link to the
authoritative work files when needed rather than copying their content. Replace
incidental names, dates, values, and paths with parameters. Never retain secrets,
unnecessary personal data, transcripts, or session identifiers in proposed handbook
artifacts.

## Return self-contained, editable requests

Lead with the useful conclusion: what could change next time, when it would help,
what supports it, and what remains uncertain. A question alone does not complete
the reflection after an answer is available. Explain a supported no-change result;
do not invent a lesson to fill a quota. For each worthwhile proposal, then return
a request the user can edit, combine, ignore, or choose, for example:

```text
Use $shape-handbook to refine [selected handbook, if known] so future [work] can
[working improvement]. Preserve [practice or distinction], define [check and
verification] where useful, and update [relevant template or existing owner].
The selected evidence shows ... It leaves ... unresolved. Keep ... visibly proposed.
```

Include enough context to shape the method without reopening the source conversation:
applicability, proposed change, useful decisions and exceptions, verification,
authoritative sources or existing material to revise, observed evidence and its limits,
and remaining dependencies. Distinguish inspected results from interpretations and
proposed work. Keep consequential inferred rules proposed until adopted. Do not invent
policy, credentials, endpoints, authority, or proof of effectiveness.

When proposing a Playbook, explicitly describe the procedure to preserve and its
outcome in the request. The user must choose that proposal or independently request
the procedure before it is created. A learning recommendation is not itself that
authorization. Suggest supporting scripts only when materially useful and explain
their proposed role within the workspace; do not generate them.

## Read-only boundary

Prefer direct file reads; when shell reads are needed, use a non-login shell to
avoid cache-writing login hooks.

Perform no filesystem writes, including reports, transcripts, temporary files,
caches, or generated artifacts. Return proposals in the response and never invoke
Shape Handbook automatically. Do not execute described work, Playbooks, scripts,
or tests; install dependencies; edit `AGENTS.md`; initialize Git; stage, commit,
push, publish; or communicate with others. Learning a method neither performs it
nor grants authority to perform it later. Another agent using the proposal retains
its separately authorized task permissions; neither operation inherits the other's
authority, and delegation cannot bypass this skill's boundaries.

Referenced files: 3

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 policy or claim the dependent work is complete.
A clear request needs no questionnaire. Review can report an unresolved choice
as a finding without requiring the user to settle it first.

## Load the guidance needed for this request

- [Setup](references/setup.md): create or adopt a handbook, or materially revise its
  README's scope, navigation, or explanation of use. Read the README starter when
  writing that explanation; return the setup blurb only for setup or adoption.
- [Practices](references/practices.md): clarify working conventions, distinctions,
  ownership, method selection, and interpretation of evidence.
- [Checks](references/checks.md): define independently evaluable expectations and
  their concrete verification.
- [Playbooks](references/playbooks.md): preserve a requested procedure and its
  optional supporting scripts.
- [Review](references/review.md): assess a handbook and relevant sources without
  executing its work; use the findings within any separately requested refinement.

Read the relevant task references together when one concern spans artifact types. Adapt
the bundled assets and applicable local templates to the task.
Create local templates only for useful reuse. Filling headings does not establish
substantive adequacy, and sample instructions do not become adopted local policy.

## Keep effects within scope

All filesystem writes, including temporary files, generated support, fixtures,
caches, and test outputs, stay inside the selected handbook. A review-only request
performs no filesystem writes. For review-only work, prefer direct file reads;
when shell reads are needed, use a non-login shell to avoid cache-writing login hooks.
Resolve destinations physically and inspect every parent directory in the path. Reject
traversal or symlinks that escape the handbook. Do not follow a handbook
symlink to widen the boundary. Re-read targets before overwriting, reconcile
concurrent changes that invalidate the edit, and preserve unrelated owner content.

Show affected paths and material decisions before writing, using existing
authorization to proceed. Recommend required outside-handbook changes instead of
making them. Never edit `AGENTS.md`, initialize Git, stage, commit, push, publish,
install outside the handbook, or communicate with others through this skill.
Do not carry out the underlying work. Supporting-script tests use only
fixtures inside the handbook and host confinement as described in the Playbook
reference; authoring a procedure and performing it remain separate operations.

## Verify the useful result

Verify local links, navigation, artifact fit, and consistency across affected
material. Then read the result as a contributor without this conversation or the
Trellis skills: can they find what applies, make the intended decision, evaluate
the result, and recognize an exception or a needed owner decision? Use a bounded
illustrative situation when it exposes ambiguity; do not perform the actual work
or present this author review as an independent agent exercise. Check that answers
changed all affected guidance and that inferred rules remain proposed until adopted.

Setup alone establishes an understandable entry point. Substantive authoring must
also supply the requested working guidance; review must explain supported findings
or why no change is needed. Keep the README's explanation of handbook use accurate
when the requested change affects it. These are completion criteria for the chosen
task, not a requirement to audit the whole handbook on every edit.

Retain useful current rationale and evidence limits, not transcripts,
session identifiers, secrets, unnecessary personal data, or obsolete accounts.
Report the decision the result now helps, changed paths or findings, checks actually
performed, and remaining dependencies. For a required user action, name the action,
its destination, and what remains incomplete until it happens. Distinguish authored
guidance, its discovery by future agents, and demonstrated use. When future reuse
is requested, check the applicable project instructions for a discovery route;
if absent, name a suitable instruction-file location and the user's remaining
action without editing it. When another agent uses the
result, preserve those limits and distinguish your completed work from its next task.
Each operation retains its own authority; a skill's restrictions do not revoke a
separately authorized task's permissions, and delegation cannot bypass the skill's
boundaries. Structural validity and instruction quality do not establish agent
compliance or correctness of the work.

Referenced files: 12