METHODOLOGY.md

# Working methods that outlast a session

Writing, research, planning, and work with customers or teammates teach us both
about the task at hand and about how to do similar tasks well. Drafts, notes,
plans, and completed results record the work. A handbook keeps the methods that
will help with the next task.

For an agent entering a new task, a nearby file and a request rarely explain the
whole working arrangement. Where is the current plan? How much detail does a
draft need? Which source supports a conclusion? Who needs to review a change?
What else needs checking when this changes? What would establish that the work is
adequate? A handbook makes these recurring decisions available without
reconstructing past conversations.

A handbook is intended to preserve working methods across tasks. Its practical
value depends on agents finding and applying the relevant material, and on people
maintaining that material as the work changes. A folder of instructions alone
establishes neither compliance nor correctness. The [contract](CONTRACT.md)
specifies what Trellis maintains.

The handbook README explains how to use its guidance without the Trellis skills.
That orientation helps a reader who reaches the folder; a pointer in the project's
instructions can help them discover it. Authoring, discovery, and successful use
are distinct achievements. Make any remaining user action concrete.

## The work and its method

The work is what people are trying to accomplish: an article, a research brief,
a team plan, or a response to a customer. Its working files hold the current
content, decisions, and results. The handbook explains how contributors approach,
organize, and review that work. Both can set requirements: keep a rule with the
work or method it governs.

For example, a team's weekly plan records priorities, dates, and responsibilities.
A practice can explain how to agree priorities, a check can ask whether commitments
have an owner and a deadline, and a Playbook can describe the planning meeting.
The agreed plan and the meeting's actual outcomes stay in the team's working files.

This keeps the handbook focused on reusable methods without making it a second
copy of current work. Link to the authoritative source when it changes a working
decision, and explain how it applies. Read mixed documents statement by statement:
a reusable meeting agenda and the current action list need different homes even
when they share a page.

A handbook can organize reusable methods as practices, checks, Playbooks, and
templates. These forms classify stored knowledge; they are not separate user
workflows. One requested improvement can clarify a practice, strengthen a check,
and adjust a template together. Choose the forms by the role each statement
serves, keep their owners distinct, and verify the change as a whole. Preserve
Playbooks only when the user asks to capture or revise a procedure.

## Practices for an area

A practice explains how to work in a particular area. Useful practices establish
ownership, meaningful distinctions, writing conventions, method selection,
interpretation of evidence, and the relationships an agent must consider. A
practice belongs when it changes a recurring decision or prevents a concrete
failure. Generic advice that adds no local meaning earns no place merely by being
true.

Practice maintenance begins with the requested area's actual content and existing
instructions. Explicit owner direction can establish a new convention. Observed
patterns can motivate a proposal, but repetition does not prove adoption or value.
An agent should distinguish an adopted rule, a documented observation, and a
suggested improvement. It must not turn accidental file structure into policy.

Organize practices around reader questions and coherent concerns. Keep entry
points short, keep detailed guidance at its owner, and let readers enter where their
task requires. The handbook need not become a tutorial or a prescribed lesson.

## Independent checks

Checks state expectations and explain how to examine them. They apply whenever
their conditions are met, including work with no Playbook. A check should make its
scope, requirement, verification, evidence, and outcome clear enough for another
agent to repeat the examination.

Many important checks require judgment: writing clarity, completeness of an
argument, agreement between notes and a report, and the strength of evidence.
Automation can support a check without completing every judgment it requires. A
link validator establishes that a target exists; a reviewer still needs to
determine whether the target supports the claim.

Checks should match the work's stated status. A precise open question can be
an adequate draft contribution. Missing evidence cannot support a resolved claim.
A readiness gate applies when someone claims readiness, rather than preventing
every earlier stage of work. Distinguish failure from unavailable evidence and
explain a decision that a check does not apply.

## Repeatable Playbooks

A Playbook preserves a recognizable task, its intended result, the judgment and
sequence needed to reach that result, and the evidence needed to establish completion.
It may connect practices, checks, templates, and local scripts. Those resources can
also have useful independent roles.

Playbook authoring follows the user's explicit request. An intended procedure can
be written before it has been proven through repeated use; writing it does not
establish its effectiveness. Learning from selected work can recommend a Playbook
when the lesson fits a repeatable task, leaving the choice to the user.

Keep a coherent task together. Split when another trigger, outcome, or maintenance
need deserves an independent home. Preserve connected phases when their judgment
and verification depend on one another. There is no required number of sections,
steps, or branches, and a handbook need not contain any Playbooks.

## Templates and substance

A template supplies a reusable structure and prompts for substance. An adopted
local template can encode area-specific expectations. It should be adaptable to
the work and defer to explicit user requirements.

For each topic that matters to the work, supply a concrete account, an exact
authoritative reference and its application, an unresolved question that affects
the work, or a reasoned exclusion.
Neither a filled heading nor additional prose demonstrates adequacy. Checks
evaluate the resulting meaning whether or not a template was used.

## Local scope and shared practice

Place each handbook with the area whose work it serves. A workspace-root handbook
can own shared practices while a writing, research, or customer-support area keeps its
specialized method nearby. Explain their scopes and link shared owners rather than
copying the same instructions into every handbook.

An agent doing cross-area work may need several handbooks. Read what applies to
the changed material and its dependencies. An area may need more specific
guidance, but a conflicting instruction needs an explicit resolution;
directory depth alone is not an authority system.

Trellis's authoring boundary remains smaller than the scope of ordinary work: its
skills write only within selected handbooks. Agents and users apply those handbooks
under the permissions of their actual tasks. References, captured procedures, and
support scripts do not expand those permissions.

## Shaping and learning

Trellis's two skills support maintaining a handbook and learning from experience.
**Shape Handbook** creates and refines the handbook in response to the user's
intent. **Learn From Work** draws reusable lessons from selected experience.
Shaping can establish, revise, or review; learning proposes. A proposed lesson
does not authorize its own adoption.
Explicit direction can shape a handbook directly, without a preceding learning
exercise or evidence of repeated successful use.

Shaping follows the requested outcome. A review examines usefulness and coherence
and returns findings without changes. A refinement request permits the relevant
handbook edits and their necessary review. Establishing a handbook provides minimum
context unless the request also calls for substantive content. The existence of a
folder alone does not decide whether to create, review, or revise it.

Useful questions return decisions to the person who owns them. Inspect available
sources first, then ask about a missing intention, tradeoff, or exception when
different answers would change the method. Obtain that answer before treating the
dependent rule as settled. The agent still owns diagnosis, organization, writing,
and verification; the user need not become a handbook designer. Clear requests
need no interview, and unresolved choices can be reported honestly in a review.

Learning can yield a useful distinction, an independent expectation, a coherent
procedure, or a better template. It need not produce all of them. A correction or
unfinished attempt can reveal a lesson, while its unobserved outcome remains
unproven. A successful result does not by itself show that every action taken was
necessary or generalizable. Keep proposed working methods separate from incidental
results, and return enough context for the user to select a shaping request without
requiring another agent to reconstruct the original conversation.

Learning questions should distinguish plausible lessons: what prompted a change,
what outcome mattered, or where a method would fail to help. Incorporate the answer
into a useful conclusion, retaining its status as the user's present account.
An unanswered question leaves a limit, not evidence of a cause. Supported learning
can also conclude that existing guidance suffices or no reusable lesson is warranted.

## Maintenance and confidence

Improve a handbook when work exposes a recurring ambiguity, a missing check, a
useful repeated method, or obsolete advice. A change to the work need not produce a
handbook change when the existing method still serves it. Remove redundant or
superseded material instead of requiring readers to reconcile historical accounts.
Git can retain history; current guidance should explain the current arrangement.

Review a handbook for usefulness as well as formal consistency: can another reader
find what applies, act without inventing missing policy, verify the result, and
locate unresolved matters? Keep the cost of maintenance proportional to the work
the handbook improves. A smaller coherent handbook is a complete result.

Keep evidence claims scoped. Instruction review establishes intended behavior;
structural checks establish selected document properties; helper tests exercise
specific program behavior; independent agent exercises demonstrate particular
uses. Confidence across varied real work requires evidence from that work.