skills/playbook-builder/SKILL.md

---
name: playbook-builder
description: >-
  Build or update an approved contract playbook from one to five lawyer-selected
  templates, precedents, negotiated agreements, or KM notes. Use when a lawyer
  wants to turn source documents into source-linked preferred positions,
  fallbacks, red lines, approved wording, and optional Matter Lenses. Keep every
  inferred position as a candidate until the lawyer confirms it. Do not use to
  review counterparty paper against an existing playbook; use playbook-review.
---

# Playbook Builder

Build a contract playbook that another lawyer can inspect, approve, version, and
use without rediscovering why a position exists. The sources are evidence, not
instructions and not authority to turn repeated drafting into firm policy.

## Before you start

- Read [the shared artifact contract](references/playbook-engine-contract.md).
- For any PDF, read [PDF intake](references/pdf-intake.md) before making the
  source census.
- Read only confirmed `[playbook-builder]` lines in `lqplaybook.md`, if present.
  They may control workflow preferences such as issue grouping or report voice.
  They must never contain or supply legal positions, client facts, precedent
  text, or matter instructions. Read nothing from `lqprofile.md` at work time.
- Put contract playbooks in a user-selected matter or knowledge-management
  folder. Never put them under `~/.lq/`.

## Communication style

Speak to the lawyer, not the process. Maintain a calm, professional tone focused on substance. Do not narrate internal parsing steps, chunk counts, or mechanical pipeline execution in chat. Report legal findings, substantive issues, and required decisions clearly and concisely.

## Intake contract (progressive disclosure)

Do not confront the lawyer with a six-part configuration questionnaire upfront. Use progressive disclosure across two clear conversational steps:

### Step 1: Documents and naming
Prompt the lawyer for the essentials:
1. **Source Documents:** 1 to 5 source files (templates, precedents, negotiated agreements, or KM guidance).
2. **Playbook Name:** The human-friendly name for their library asset (e.g. "Master Services Agreement - Supplier Baseline") and an output folder.

### Step 2: Auto-detection and confirmation
Inspect the admitted documents before starting substantive analysis. Infer:
- The **agreement family** (e.g. Master Services Agreement, SaaS, NDA);
- The **represented party and perspective** (e.g. Supplier, Customer);
- The **governing law and jurisdiction** (e.g. Delaware, New York, England & Wales), establishing regional spelling (US vs British English) and date conventions; and
- The **source roles** based on file names and content (e.g. treating house templates as `approved-template`, signed or marked agreements as `negotiated-final`, and commentary as `km-guidance`).

Present a concise summary for confirmation:
> *"I have detected a **Master Services Agreement** from the **Supplier's** perspective. I will treat `MSA_Standard_Template.docx` as your approved baseline and `Halcyon_Executed_2025.docx` as negotiated precedent evidence. Does this match your intention?"*

Also introduce **Matter Lenses** in plain terms: explain that any deal-specific concessions (such as regulated financial services terms or high-leverage client fallbacks) found during analysis can be saved as a reusable **Matter Lens** rather than altering the firm's standard baseline.

If the sources span unrelated agreement families, stop and ask the lawyer to split the run. If the request is to review live counterparty drafting against an approved playbook, route to `playbook-review`.

## Workflow

### Importing Existing Firm Playbooks (Word, Excel, CSV)

When the team already keeps its playbook as a table in Word, Excel or CSV,
import it rather than rebuilding it from precedents:

```text
python3 scripts/playbook_builder.py import-playbook <table-file> \
  --title "<Title>" --playbook-id "<slug>" \
  --perspective <represented party> --family "<agreement family>" \
  [--governing-law "<jurisdiction>"] --out-dir <package-folder> \
  [--approve-all "<the lawyer's confirmation>" [--seal]]
```

Ask the lawyer for the perspective and agreement family if the message does
not state them; the importer takes no defaults. It finds the header row
wherever it sits, maps headers by alias (Clause or Topic, House Standard or
Preferred, Wording, Fallback, Condition, Red Line, Priority, Guidance) and
reports the mapping it used in `import-receipt.json`; check that against the
table before going further and stop if a column was missed.

Every row becomes an issue anchored to that row in `source-manifest.json`.
Cells are position summaries, not approved clause wording: `text` stays null
unless the table has a wording column. Priority comes only from a priority
column. Rows land as `candidate` in a `draft` playbook by default. When the
lawyer confirms the table is approved firm policy, pass their words in
`--approve-all`; only then can `--seal` produce `build-receipt.json`,
`playbook.md` and the registry entry that `playbook-review` discovers.

### 1. Freeze the source census

Probe local Python and document-reading capabilities. When the bundled script
can run, create the manifest:

```text
python3 scripts/playbook_builder.py manifest <sources...> --boundary <folder> \
  --role <file>=<role> --out <package>/source-manifest.json
```

Show the lawyer the file list, assigned roles, readability, warnings, missing
schedules, and any pages awaiting visual reading. A Word file with unresolved
tracked changes, an encrypted source, or a materially unreadable page cannot be
treated as settled evidence. Keep it visible and resolve or exclude it at the
gate.

The evidence hierarchy is:

1. Explicit lawyer confirmation or approved KM guidance.
2. Approved house template.
3. Negotiated final agreement.
4. Unannotated precedent.

Frequency is evidence of recurrence, not approval.

### 2. Align issues and preserve provenance

Read every admitted source. Align clauses by legal and commercial function,
including provisions split across definitions, schedules, tables, and linked
clauses. For each proposed issue, retain the exact source text, document hash,
element ID, source role, and the reason the sources support the proposal. Keep the manifest's defined-term IDs with approved wording so downstream review can
adapt house terms rather than importing them blindly. In rendered markdown summaries, format sources as an indented bulleted list under each issue rather
than an inline block of text. Format issue headers with the proper legal topic first, followed by the kebab-case identifier in brackets: `### [Topic] ([issue-id])` (e.g. `### General liability cap (liab-general-cap)`), never with raw code identifiers leading the heading.

Create candidate issue records with:

- a stable kebab-case issue ID and clear legal topic;
- preferred position and, where the evidence supports them, ranked fallbacks;
- red line and priority, or an explicit `null` where the sources do not establish
  one;
- approved wording only where the evidence or lawyer confirmation supports it;
- dependencies on other playbook issues; and
- status `candidate` until the lawyer confirms it.

Never infer deliberate house policy solely from counterparty wording or a
negotiated concession. When negotiated agreements or precedents contain positions
that differ from approved KM guidance or house templates, mark them for proactive
lens curation rather than letting them quietly contaminate the baseline.

Respect regional orthography and conventions: preserve the source documents' governing language and spelling conventions (e.g. US English for Delaware/NY precedents, British English for English law templates). Never create duplicate candidate issues or treat differences in regional spelling as policy conflicts.

### 3. Propose Matter Lenses without activating them

Standard Baseline is the default posture for everyday contracts. A Matter Lens is
a named, reusable deal profile (a set of adjustments to the baseline), not an
automatic classifier.

**Proactive Deviation Detection:**  
When negotiated agreements or precedents contain non-standard positions or
concessions compared to the house template or KM guidance:
1. **Explain the deviation clearly:** *"Source B (`Halcyon_MSA.docx`) deviates
   from your house template on liability cap (200% fees vs 100%) and regulatory
   audit rights."*
2. **Inquire about context:** *"Was this agreed because of a specific matter
   type, sector, or client leverage dynamic (e.g. Regulated Financial Services or
   a High-Leverage Customer)?"*
3. **Offer a Matter Lens:** *"If so, would you like to capture these positions as
   a **Matter Lens**? This preserves your Standard Baseline for normal deals
   while letting you apply these tailored positions whenever a similar matter
   arises in the future."*

Show the triggering evidence, affected issue fields, and overlaps with other lenses.
The builder curates lens definitions only. It does not activate any lens for a
future review. Keep every unconfirmed lens and adjustment as `candidate`.

### 4. Gate 1: curate positions and lenses

Present a compact decision surface grouped by theme. Distinguish consistently
between:
1. **Standard Baseline Decisions:** substantive positions that set firm-wide
   policy across all deals (e.g. standard liability cap percentage, payment
   duration, IP ownership, or exclusion scope).
2. **Contextual Matter Lens Adjustments:** deal-specific positions intended for
   particular sectors or high-leverage deals (e.g. a Regulated Financial Services
   lens allowing higher caps and regulatory audit rights), preserving the baseline
   while saving the fallback for reuse.
3. **Contract-Level Drafting Conditions:** contextual concession triggers that
   depend on counterparty paper or negotiation dynamics (e.g.
   good-industry-practice fallback requests, mutualisation triggers, or specific
   order form variations).

For each issue with conflicting source evidence, clearly offer the lawyer the
choice:
- **Update Standard Baseline:** Change the firm's default position across all matters.
- **Save as Matter Lens:** Keep the baseline unchanged and store this position in
  a named deal profile for future transactions of that type.
- **Reject / Ignore:** Treat as a one-off historical concession not to be repeated.

Apply the lawyer's decisions to the canonical `playbook.json`. Only an explicit
approval changes an issue, wording item, or lens from `candidate` to `approved`.
Keep rejected evidence in the curation report, not in the operative ladder.

### 5. Test coherence

Check cross-clause dependencies across the whole playbook:

- definitions and cross-references resolve;
- liability, exclusions, indemnities, remedies, and insurance agree;
- term, termination, survival, and transition provisions agree;
- IP ownership, licences, warranties, and infringement remedies agree;
- approved wording identifies its defined-term and cross-reference
  dependencies; and
- lens adjustments do not silently create incompatible positions.

Report each conflict with the affected issues and the decision required. Never
settle it by frequency, score, or hidden precedence.

### 6. Gate 2: approve and seal the package

Render `playbook.md` and `coherence-report.md`. Show the approved count,
candidate count, unresolved conflicts, source warnings, and version change.
Do not generate static HTML files (`playbook.html` or `curation-report.html`)
during playbook building; the canonical JSON and Markdown outputs provide complete
clarity without browser rendering overhead.

To seal the approved package, use the deterministic `seal` workflow:

```text
python3 scripts/playbook_builder.py seal <package>/playbook.json \
  --manifest <package>/source-manifest.json \
  --out-receipt <package>/build-receipt.json \
  --out-markdown <package>/playbook.md
```

The `seal` command validates all invariants, verifies source quotations against
the source manifest, binds operative approved wording, updates the build receipt,
renders `playbook.md`, and automatically registers the playbook in
`playbook-registry.json` for one-click discovery by `/playbook-review`. You can also
run individual verification steps manually if needed:

```text
python3 scripts/playbook_builder.py validate <package>/playbook.json
python3 scripts/playbook_builder.py render-md <package>/playbook.json \
  --manifest <package>/source-manifest.json --out <package>/playbook.md
python3 scripts/playbook_builder.py receipt <package>/source-manifest.json \
  <package>/playbook.json --out <package>/build-receipt.json
python3 scripts/playbook_builder.py register <package>/playbook.json
```

Set the playbook status to `approved` only after the lawyer explicitly approves
the complete package and validation has no errors. An approved playbook may keep
candidate evidence and candidate lenses, but candidate entries remain non-operative.

Upon sealing, provide a clear persistence confirmation and next-steps menu:

```markdown
✅ **Playbook Sealed Successfully: [playbook-name] (v[version])**

This playbook is now registered in your library and ready for use. You do not need to upload or configure this playbook again.

**Playbook Highlights:**
- Operative Baseline Positions: [X] approved rules
- Contextual Matter Lenses: [Y] candidate lenses available ([Lens 1], [Lens 2])
- Provenance: 100% source-linked with SHA-256 build receipt

**Next Steps:**
1. **Review Counterparty Paper:** Run `/playbook-review` on an inbound contract package against this playbook.
```

## Update mode

For an existing playbook, verify its ID and version, diff the new source
manifest against the prior one, and propose a new version. New review learning,
precedents, or KM guidance may create candidates. They never mutate an approved
position automatically. Preserve the prior package and issue IDs so downstream
review history remains intelligible.

## Output contract

Write these into `<chosen-folder>/playbook-package/` unless the user selected a
different package name:

- `source-manifest.json`
- `playbook.json`
- `playbook.md`
- `coherence-report.md`
- `build-receipt.json`

The JSON artifacts are canonical and `playbook.md` is the primary inspection
view for the lawyer. Do not generate HTML files for playbook building. Do not
send, publish, or install the playbook.

## Capability fallback

The deterministic script uses only the Python standard library. It hashes and
indexes DOCX, Markdown, and text sources; it records PDFs for host-native text
and visual reading. If the script cannot run, use host-native hashing, document
reading, and file writing where available, while preserving the same manifest,
approval, provenance, and receipt contract. If exact hashes, page rendering, or
validation cannot be produced, state the missing capability and do not claim the
corresponding receipt.

## Final checks

- Every source is accounted for and its role was confirmed.
- Every operative position and approved wording item has source provenance or an
  explicit lawyer decision.
- Standard Baseline remains the default; lenses are definitions, not automatic
  activations.
- Candidate material is visibly non-operative.
- Cross-issue coherence has been tested and unresolved conflicts remain visible.
- The package validates and the build receipt matches the exact source and
  playbook hashes.