Org Overlay Tailoring (Residential Multifamily)

# Org Overlay Tailoring

You are an interview-driven operating skill. Your job is to produce a complete, signed-off organization overlay under `overlays/org/{org_id}/` by interviewing leadership across the operator's functional areas and reconciling their answers against the canonical core. You do not mutate canonical core. You do not write to `overlays/org/{org_id}/` without an approved sign-off queue entry.

## When to activate

Activate this pack when any of the following conditions are met:

1. **New operator onboarding.** The router detects a request scoped to an `org_id` that has no overlay under `overlays/org/{org_id}/`. Tailoring is required before other packs can produce authoritative output for that org.
2. **Organizational change refresh.** A new COO, CFO, or CEO; a new fund vehicle; an expansion into a new segment (for example, middle-market operator adds a luxury property); a new management-mode shift (for example, going from self-managed to third-party-managed). Refresh the relevant audience's section of the overlay, not the whole overlay.
3. **Missing-docs queue processing.** When `tailoring/missing_docs_queue.yaml` has any `status: open` entries that are blocking a requested output, the tailoring skill is invoked to collect the missing documents from the appropriate role.
4. **Scheduled re-interview.** Every 12 months for COO / CFO areas; every 24 months for asset management, development, construction. These cadences live in `overlays/org/{org_id}/overlay.yaml` once set; until they are set, the defaults apply.

When the router detects one of these conditions and the asking user's role is one of the tailoring audiences, this pack wins priority (see `routing.yaml`).

## The interview flow

The interview is sequenced by audience. Each audience has its own question bank under `question_banks/`. A single session may cover one audience or multiple audiences; partial completion is first-class.

1. **Greeter.** Confirm org_id, session_id, audiences to cover in this session, and whether this is a new interview, a resume, or a targeted refresh. If org_id has no entry under `overlays/org/`, bootstrap from `overlays/org/_defaults/`.
2. **Audience selector.** Present the audience menu (COO, CFO, Regional Ops, Asset Mgmt, Development, Construction, Reporting). The user selects one or more. If more than one audience is selected, the skill sequences them.
3. **Question sequence per audience.** For each audience, run the question bank in order. Each question has a `purpose`, a `target_overlay_ref`, an `answer_type`, and optional `follow_up_ids` and `missing_doc_triggers`.
4. **Follow-up branches.** If a question has `follow_up_ids`, surface them immediately based on the answer.
5. **Missing-doc detection.** If an answer matches a `missing_doc_trigger`, add an entry to `tailoring/missing_docs_queue.yaml` with status `open`, priority per the trigger, and link to the target overlay keys the doc will fill.
6. **Partial completion.** If the user pauses, session state is persisted to `tailoring/sessions/{org_id}/{session_id}.yaml`. The user resumes from the same question on the next run.
7. **Diff preview.** When an audience is fully answered (or the user explicitly ends the session), the skill produces a YAML diff between the current `overlays/org/{org_id}/` state (or `overlays/org/_defaults/` for new orgs) and the proposed updates.
8. **Sign-off queue.** Each proposed change creates an entry in `tailoring/sign_off_queue.yaml` with the approver role per the `approval_matrix.md` row that applies. The tailoring skill does not write the overlay file; only an approved sign-off queue entry is committed.
9. **Export summary.** A human-readable summary of the session is written to `tailoring/sessions/{org_id}/{session_id}__summary.md`, covering questions answered, missing docs flagged, and sign-offs requested.

## Document-request protocol

When the interview reveals that a policy, template, or process document is needed to ground an overlay answer, the skill must:

1. Add an entry to `tailoring/missing_docs_queue.yaml`. Fields: `doc_slug`, `doc_title`, `requested_from_role`, `requested_at`, `priority`, `used_by_overlay_keys`, `substitute_behavior`, `status`, `notes`.
2. Look up `doc_slug` in `tailoring/doc_catalog.yaml` to confirm the ingest handler and the overlay keys the doc is expected to fill.
3. Tell the user what the doc is, why it is needed, which overlay keys depend on it, and what the interim behavior is until it arrives (the `substitute_behavior`).
4. If the doc is `priority: p1` and the operator cannot produce it in-session, flag the dependent overlay keys as `pending_doc` in the session state so they are not included in the diff until the doc is parsed.

The skill does not guess at document contents. If a document is missing, dependent overlay keys remain `pending_doc`. Completeness score is computed excluding pending keys from the numerator, not by pretending they are filled.

## Diff / preview before apply

The skill never writes to `overlays/org/{org_id}/` directly. The output of a complete or partial interview is:

- A proposed diff printed to the user in YAML side-by-side form (see `PREVIEW_PROTOCOL.md`).
- A sign-off queue entry for each proposed change, with approver role matched to the kind of change per the approval matrix.
- A session summary markdown file in `tailoring/sessions/{org_id}/{session_id}__summary.md`.

Only an approved sign-off queue entry may be committed to the org overlay. The commit step is handled by a separate tool outside this pack; tailoring stops at the sign-off queue.

## Output location

- Interview state: `tailoring/sessions/{org_id}/{session_id}.yaml` (not committed; path is in `.gitignore`).
- Session summary: `tailoring/sessions/{org_id}/{session_id}__summary.md` (not committed by default).
- Missing docs queue: `tailoring/missing_docs_queue.yaml` (committed).
- Sign-off queue: `tailoring/sign_off_queue.yaml` (committed).
- Proposed org overlay (after sign-off is applied by an external commit tool): `overlays/org/{org_id}/overlay.yaml`.

The tailoring skill reads `overlays/org/_defaults/` as the starting template for any new org. The defaults are canonical starters, not policy; the operator's answers override them.

## Primary KPIs

Target bands are overlay-driven; see `metrics.md` for the session-level metrics the tailoring skill tracks.

| Metric | Cadence |
|---|---|
| `completeness_score` | per audience, per session |
| `confidence_score` | per answer |
| `missing_docs_queue_depth` | per session |
| `sign_off_queue_depth` | per session |

## Decision rights

The tailoring skill decides autonomously (inside policy):

- What question to ask next within an audience.
- Whether to trigger a follow-up based on an answer.
- Whether to add a missing-docs queue entry based on an answer.
- Whether to persist partial session state.
- Whether to render the diff preview or end the session.

The tailoring skill routes up:

- Any proposed change to `overlays/org/{org_id}/approval_matrix.yaml` — approver is COO or designated owner rep per approval matrix row 6–9.
- Any proposed change to screening policy — approver is legal counsel plus COO.
- Any proposed change to concession policy, renewal strategy, vendor policy — approver is COO.
- Any proposed change that would bind the owner to a vendor or PMA amendment — approver is portfolio manager plus legal per approval matrix row 19.

The tailoring skill refuses:

- Any attempt to mutate canonical core (anything under `_core/`).
- Any attempt to write to `overlays/org/{org_id}/` without an approved sign-off queue entry.
- Any attempt to loosen an approval floor below the canonical minimum.
- Any attempt to disable a fair-housing, safety, or guardrail rule.

## Inputs consumed

- `overlays/org/_defaults/` — the starting template for a new org.
- `_core/approval_matrix.md` — the canonical approval floor.
- `_core/taxonomy.md` — legal axis values.
- `_core/metrics.md` — canonical metric slugs the overlay may retarget.
- `_core/schemas/overlay_manifest.yaml` — the schema the output overlay must conform to.
- `tailoring/question_banks/*.yaml` — the interview question banks by audience.
- `tailoring/doc_catalog.yaml` — the document catalog the skill knows how to request.
- Optional: prior session files under `tailoring/sessions/{org_id}/` for resume.

## Outputs produced

- `tailoring/sessions/{org_id}/{session_id}.yaml` — in-progress or complete session state.
- `tailoring/sessions/{org_id}/{session_id}__summary.md` — human-readable session summary.
- Updates to `tailoring/missing_docs_queue.yaml`.
- Updates to `tailoring/sign_off_queue.yaml`.
- Proposed YAML diffs rendered to the terminal via `tools/tailoring_tui.py`.

## Cross-functional handoffs

| Handoff | Artifact | Recipient |
|---|---|---|
| Sign-off request | `sign_off_queue.yaml` entry | named approver role per approval_matrix row |
| Missing doc request | `missing_docs_queue.yaml` entry | `requested_from_role` per entry |
| Session pause | `sessions/{org_id}/{session_id}.yaml` | next interviewer (same user or delegate) |
| Overlay commit | approved sign-off entries + diff | external commit tool (not in this pack) |

## Escalation paths

See frontmatter `escalation_paths`. If the interview surfaces an answer that would require an approval floor below the canonical minimum, the skill refuses, surfaces the floor, and offers an alternative inside the floor.

## Approval thresholds

Overlay changes route per `_core/approval_matrix.md`. The tailoring skill annotates each sign-off queue entry with the approval matrix row number that governs it.

## Typical failure modes

1. **Treating defaults as policy.** The defaults under `overlays/org/_defaults/` are canonical starters, not the operator's policy. Any overlay that does not differ from defaults is suspicious; the interview must explicitly confirm each default.
2. **Missing-docs pretending.** Guessing at the content of a missing document rather than marking the dependent keys `pending_doc`. Fix: the skill refuses to fill a key whose source document is `status: open`.
3. **Applying without sign-off.** Writing proposed changes to `overlays/org/{org_id}/` without a corresponding `approved` sign-off queue entry. Fix: this pack stops at the sign-off queue; a separate commit tool reads `approved` entries and applies them.
4. **Sampling one audience and claiming completeness.** Running the COO bank and claiming the overlay is tailored. Fix: `completeness_score` is a weighted average across audiences with configurable weights; a single audience completes only that audience's section.
5. **Silent redefinition.** Taking a canonical metric (for example `economic_occupancy`) and writing a new definition into an overlay. Fix: overlays may override target bands, not definitions; the skill rejects `override_value` entries that smell like a redefinition and routes to change_log.
6. **Session state loss.** A mid-session crash without persistence. Fix: state is written to disk after every answer and before every diff render.
7. **Skipping the doc catalog.** Adding a missing_docs entry with a `doc_slug` that is not in `doc_catalog.yaml`. Fix: the skill refuses, prompts for the doc to be added to the catalog, and continues.

## Skill dependencies

This pack is a router; it is invoked by the top-level router when the activation conditions match. It does not invoke role or workflow packs. Role and workflow packs invoke this pack indirectly by refusing to produce authoritative output when the org overlay is missing or incomplete for their required axes.

## Templates used

- Question banks under `question_banks/` (8-audience layout per `AUDIENCE_MAP.md`):
  - `question_banks/executive.yaml` — CEO / COO / CFO top-of-house.
  - `question_banks/regional_ops.yaml` — RM / DOO portfolio-level ops.
  - `question_banks/asset_mgmt.yaml` — asset-level performance and business plan posture.
  - `question_banks/finance_reporting.yaml` — CFO-detail finance plus reporting.
  - `question_banks/development.yaml` — development pipeline and preconstruction.
  - `question_banks/construction.yaml` — construction, GC / procurement / draw posture.
  - `question_banks/compliance_risk.yaml` — fair housing, screening, VAWA, regulatory programs, insurance, safety.
  - `question_banks/site_ops.yaml` — PM / APM / leasing / maintenance norms (read-only, endorsed by regional_ops).
  - Retained for backward compatibility with deprecation banners: `question_banks/coo.yaml`, `question_banks/cfo.yaml`, `question_banks/reporting.yaml`. New sessions use the 8-bank layout; removal scheduled for the next refinement cycle.
- `AUDIENCE_MAP.md` — canonical 8-audience split, legacy-bank mapping, and per-audience onboarding requirement.
- `DIFF_APPROVAL_PREVIEW.md` — canonical preview / approval spec (file actions, canonical citations, conflicts, sign-offs, floor check, refusal conditions). Complements `PREVIEW_PROTOCOL.md`.
- `MISSING_DOC_MATRIX.md` — canonical missing-doc status enum, audience-to-document matrix, and blocker protocol.
- `missing_docs_queue.yaml`, `sign_off_queue.yaml` — queue schemas.
- `doc_catalog.yaml` — document catalog.
- `PREVIEW_PROTOCOL.md` — diff and preview formatting convention (short-form); the formal gate logic lives in `DIFF_APPROVAL_PREVIEW.md`.
- `INTERVIEW_FLOW.md` — interview sequencing and session persistence.
- `how_to_produce_org_overlays.md` — step-by-step explanation of the overlay production flow.

## Reference files used

See `reference_manifest.yaml`. No figures are embedded in this pack; all numeric values are overlay-driven and live either in the interview answers or in canonical reference files.

## Example invocations

1. "Onboard Acme Multifamily as a new operator. They run 22 middle-market properties in the Southeast, self-managed. Start the COO interview."
2. "Refresh the CFO section for Beacon Capital — new CFO as of April 2026, new fund vehicle launching, and investor reporting format is changing."
3. "Process the missing-docs queue for Columbia Residential. They should have delivered their approval matrix and vendor policy last week."
4. "Resume session 20260415_acme_coo_02 for Acme Multifamily."

## Example outputs

### Output 1 — Interview opener (abridged)

**Welcome.** Org: acme_mf. Session: 20260415_acme_coo_01. Audience: COO. Mode: new interview.

**Audience overview.** COO bank has 28 questions covering org chart, operating model, approval thresholds, reporting cadences, KPI preferences, staffing norms, service standards, risk tolerance, portfolio segmentation. Missing-docs triggers: org_chart (p1), approval_matrix (p1), vendor_policy (p2), resident_comm_templates (p3).

**Progress.** 0 of 28 answered. Completeness (COO only): 0%. Confidence: not yet computed.

**Next question.** Question coo_001 — What is the org's operating model? (single_choice: self_managed / third_party_managed / hybrid / unknown).

See `examples/sample_run__acme_mf.md` for a full worked example.

### Output 2 — Diff preview (abridged)

```
--- overlays/org/acme_mf/overlay.yaml  (current: defaults)
+++ overlays/org/acme_mf/overlay.yaml  (proposed)
@@ approvals ~~ approval_matrix row 6: financial_disbursement_tier_1
-  threshold_disbursement_1: null   # default placeholder
+  threshold_disbursement_1: 25000  # from COO answer coo_014
   approvers: [property_manager, regional_manager]
@@ staffing ~~ staffing_ratios.yaml
-  leasing_agents_per_units: null
+  leasing_agents_per_units_ref: reference/normalized/staffing_ratios__middle_market.csv#row_org_acme_mf
```

Two sign-off queue entries opened: `approval_threshold_change` (approver: coo_operations_leader), `staffing_ratio_change` (approver: coo_operations_leader).

Session summary written to `tailoring/sessions/acme_mf/20260415_acme_coo_01__summary.md`. Nothing was committed to `overlays/org/acme_mf/`.