# SKILL — lfcs-spec-summarise

## Purpose

Read a spec PDF (TfNSW R-series, Sydney Water, AS/NZS, council standard) and write a structured MD summary to `lfcs-standards/specs/{spec_code}-summary.md`. Lets downstream skills (pricing, bid-prep, RFI drafting) query the spec via the MD summary instead of re-reading the multi-page PDF every time. Saves big tokens on every skill run that touches a spec-governed item.

Closes Gap #2 from the YouTube transcript gap analysis Rocky shared 2026-05-04 ("mirror static text documents as MD for fast AI ingest").

Created 2026-05-04 PM late by cowork-lfcs Phase 7.

## Trigger

User says any of:
- "Summarise spec [path or code]"
- "Build spec summary for R11"
- "I dropped a new spec — summarise it"

Or invoked programmatically by `lfcs-project-init` v2 (Phase 7) when a job's `03a/` folder contains spec PDFs (matched by filename pattern: `FRBR_R*`, `R0*`, `B*`, `AS*`, `SydneyWater_*`, etc.).

## Inputs

Required (one of):
- `spec_pdf_path` — absolute path to the spec PDF in vault
- `job_folder` — absolute path to a job; auto-discovers spec PDFs in `03a/` matching the patterns above

Optional:
- `spec_code` — explicit override (e.g. `TfNSW-R11-Ed5Rev8-PeakhurstOct2024`); if absent, derive from filename
- `mode` — `full` (default — full structured summary) or `quick` (only Hold Points + Witness Points + key clauses, ~200-line cap)

## Behaviour

1. **Pre-flight** — confirm input PDF exists; if `job_folder` mode, scan for spec patterns. Abort if zero specs found.
2. **Extract spec metadata** from PDF (cover page + first 2 pages):
   - Standard body (TfNSW / Sydney Water / AS/NZS / Council / Other)
   - Title (e.g. "Stormwater Drainage")
   - Edition / Revision (e.g. "Ed 5 Rev 8")
   - Project-specific date (e.g. "October 2024" — common on TfNSW project-specific revs)
   - Page count
3. **Read PDF body** — section-by-section text extraction. Handle large specs (50-200 pages) by chunked reading if needed. Cowork's Read tool handles PDF text natively.
4. **Extract structured content** — categorise by section:
   - **Hold Points** (look for "Hold Point" headings + clause numbers + descriptions)
   - **Witness Points** (look for "Witness Point" / "Notify the Principal" patterns)
   - **Identified Records** (look for "Identified Record" headings — common in TfNSW R-series)
   - **Mandatory clauses** (Project Quality Plan, Cert of Conformity, Method Statements)
   - **Material specs** (concrete grades, reo grades, AAR / NATA / ACRS requirements)
   - **Workmanship / construction tolerances**
   - **Inspection + testing requirements**
   - **Spec-specific gotchas** (any clause flagged "shall not", "minimum lead time", "subject to approval")
5. **Write `{spec_code}-summary.md`** to `Operations/lfcs-standards/specs/` with frontmatter:
   ```yaml
   ---
   spec_code: TfNSW-R11-Ed5Rev8-PeakhurstOct2024
   standard_body: TfNSW
   title: Stormwater Drainage
   edition: Ed 5 Rev 8
   project_specific_date: 2024-10-01
   source_pdf_vault_path: 11_OpsMan_LFCS/Operations/Jobs/.../FRBR_R011_E5_R8_FINAL.pdf
   pages: 67
   summarised: 2026-05-04
   summarised_by: cowork-lfcs (Phase 7 lfcs-spec-summarise)
   summary_mode: full
   ---
   ```
   Body sections: TL;DR (5 lines), Hold Points table, Witness Points table, Identified Records table, Mandatory clauses, Material specs, Workmanship/tolerances, Inspection + testing, Gotchas, Cross-references (other specs this references, e.g. R11 references R53), Application to LFCS scope (1-paragraph: how this spec affects LFCS pricing/programme/QA admin).
6. **Update Airtable Specifications row** (if Spec Code matches an existing record) — populate Notes field with summary first paragraph + link to vault path. Upsert via `lfcs-airtable-sync`.
7. **Append project log + daily note + skills/_Log.md** per AI Team Protocol.

## Files to read (in order)

```
HQ-Vault/_System/CLAUDE.md
HQ-Vault/11_OpsMan_LFCS/_Brain/CLAUDE.md
HQ-Vault/11_OpsMan_LFCS/Operations/lfcs-standards/specs/TfNSW-R11-Ed5Rev8-PeakhurstOct2024-summary.md  ← regression fixture (canonical example built Phase 7)
HQ-Vault/11_OpsMan_LFCS/Operations/lfcs-standards/concepts/TfNSW-R0220-pit-pattern.md  ← references R11 + R53; concept note shows how spec summaries get used downstream
{spec_pdf_path} OR {job_folder}/03 - Plans and Specifications/03a - Issued for Construction/{spec_pdf}.pdf
```

## Airtable behaviour

- **Reads:** Specifications table (search by Spec Code primary field for upsert idempotency).
- **Writes:** Specifications table — upserts the matching row's Notes field with summary first paragraph + Hold Points Count + Witness Points Count derived from extraction. Calls `lfcs-airtable-sync target_table=Specifications` as final step.
- **Idempotency:** searches by Spec Code primary field; updates existing row, does not duplicate. Re-running on same spec PDF = same Airtable state.

## Output format

To user (terminal):

```
✓ Spec summarised: {spec_code}
  Source PDF: {vault_path}
  Pages: {n}
  Hold Points extracted: {n}
  Witness Points extracted: {n}
  Identified Records: {n}
  Mandatory clauses: {n}

  Output: HQ-Vault/.../lfcs-standards/specs/{spec_code}-summary.md
  Airtable: Specifications {rec_id} updated with Notes summary + counts

  Application to LFCS scope: {1-paragraph}
```

## Hard rules

- **Verbatim Hold Points + Witness Points + clause numbers.** Don't paraphrase — these are contractually significant. Quote them exactly with clause reference (e.g. "R11 4.4.2: Cert of Conformity for joints pre-backfill").
- **No invention.** If a section isn't in the spec, leave it blank or note "not present in this spec".
- **Append-only on `{spec_code}-summary.md`.** If file exists, abort + ask user (regenerate from scratch or merge).
- **Read-before-edit** every spec PDF each invocation (specs get re-issued; the latest version may differ).
- **Vault markdown is source of truth.** If Airtable Specifications.Notes diverges from the summary MD, the MD wins.
- **Failure non-blocking.** If `lfcs-airtable-sync` fails, the summary MD is still successful — log to `_System/Conflicts.md` and continue.

## Dependencies

- Cowork PDF Read tool (or CC CLI pdfplumber for headless mode)
- 2626's R11 spec PDF (regression fixture for testing)
- `lfcs-airtable-sync` v1+ (final-step adapter call)

## Regression test

Running `lfcs-spec-summarise spec_pdf_path={2626 R11 path}` should produce:
1. `lfcs-standards/specs/TfNSW-R11-Ed5Rev8-PeakhurstOct2024-summary.md` with frontmatter + body sections per the schema above
2. Airtable Specifications row `recplbEyXCGbAkSWm` (active R11 from CCC's Phase 3 seed) updated with summary first paragraph + Hold Points Count + Witness Points Count
3. Re-running on the same PDF = no duplicate, MD aborted with regenerate-vs-merge prompt

## Failure modes

| Failure | Detection | Recovery |
|---|---|---|
| PDF unreadable / image-only | Read tool returns empty text | Flag in Notes, abort summary, recommend manual transcription OR vision-pass on each page |
| Spec code can't be derived from filename | Pre-extract metadata fail | Ask user for explicit `spec_code` input |
| Multiple specs in 03a folder (job_folder mode) | Auto-discover finds >1 PDF | Surface list, ask user which to summarise OR run per-file in batch |
| `{spec_code}-summary.md` already exists | Pre-check | Abort + ask user (regenerate or merge) |
| Hold Points / Witness Points extraction returns zero on a spec known to have them | Post-extraction count check | Flag in summary "AUTO-EXTRACTION INCOMPLETE — manual review required"; don't silently produce empty sections |