On main: Pre-merge: synced agent files

docs/legal-decision-lessons.md

@@ -161,3 +161,94 @@ Our skill was "over-indexed" on one case type (הכט = rejected appeal). The co
 - Created `create-decision-structure.cjs` script for generating structure DOCX
 - Key innovation from Arieli: "ההליכים בפני ועדת הערר" as separate section (Block ח)
 - "Judge Test": every block written as if administrative court judge reads cold
+
+---
+
+## Lessons from Systematic Corpus Analysis (24 decisions, April 2026)
+
+### Source
+- All 24 proofread decisions in `/data/training/proofread/`
+- Full analysis: [`docs/corpus-analysis.md`](corpus-analysis.md)
+- Date: April 2026
+
+### 12. System Learned Style but Not Substantive Content
+- **Problem:** Dafna reviewed Kiryat Yearim draft and noted missing planning discussion in block-yod
+- **Root cause:** The block-yod prompt taught CREAC methodology and "answer all claims" but never said "in licensing cases, include comprehensive planning discussion"
+- **Fix:** Content checklists added to `lessons.py` (`CONTENT_CHECKLISTS`), injected into block-yod prompt via `{content_checklist}`
+- **Applied to:** `lessons.py`, `block_writer.py`
+
+### 13. Corpus Composition — All Licensing, No Betterment Levy
+- All 24 training decisions are licensing/construction (1xxx)
+- Zero betterment levy (8xxx) decisions in corpus
+- Not a current priority gap — focusing on licensing first
+
+### 14. Planning Discussion Patterns in Licensing Decisions
+- **Always present** when the appeal reaches substantive planning questions
+- **Never present** when the appeal is purely jurisdictional or property-based
+- **Structure**: broad planning context → direct plan provision citations (200-600 words) → application to specific case → planning conclusion
+- **Deepest planning**: פרומר (pure plan interpretation), לבנון (height/building appendix), בית הכרם (multi-plan TAMA 38)
+- **No planning**: טלי-אביב (property only), גבאי (jurisdiction only)
+
+### 15. Five Appeal Subtypes Identified (Not Just Three)
+Licensing appeals are not homogeneous — the discussion structure varies significantly:
+1. **Substantive licensing** — full planning discussion + legal analysis (majority of cases)
+2. **Threshold/jurisdiction** — legal analysis only, no planning
+3. **Property-focused** — תימוכין קנייניים, minimal planning
+4. **TAMA 38** — balancing public interest + planning + neighbor impact
+5. **Deviant use (שימוש חורג)** — deep plan interpretation across multiple plans
+
+### 16. Chair Feedback System Established
+- DB table `chair_feedback` records Dafna's comments on drafts
+- Categories: missing_content, wrong_tone, wrong_structure, factual_error, style, other
+- MCP tools + UI page for recording and reviewing feedback
+- First entry: Kiryat Yearim — missing planning discussion (2026-04-12)
+
+---
+
+## Lessons from External Expertise Research (April 2026)
+
+### Source
+- Federal Judicial Center, *Judicial Writing Manual* (1991, 2nd ed. 2020)
+- Bryan Garner, *Legal Writing in Plain English* (2001)
+- Scalia & Garner, *Making Your Case: The Art of Persuading Judges* (2008)
+- Richard Posner, *How Judges Think* (2008)
+- Full texts stored in: `docs/sources/`
+
+### 17. Methodology Document Created — Separating "How to Think" from "How to Write"
+
+**Problem:** The system knew Dafna's STYLE (SKILL.md) and WHAT TOPICS to cover (content checklists), but had no formal methodology for HOW TO REASON through a decision — the analytical stages, when to balance, how to structure arguments, how to handle counterarguments.
+
+**Fix:** Created `docs/decision-methodology.md` — a standalone analytical methodology document based on synthesis of all four external sources. 3,400 words, 12 sections, 10 guiding principles. Covers: pre-analysis, threshold questions, issue ordering, syllogistic structure (CREAC), balancing/proportionality, claims handling (steel-man, bundling), quotation technique (sandwich), factual findings vs. legal conclusions, disposition, writing techniques, analogy/precedent, editing checklist.
+
+**Key principle:** Methodology is UNIVERSAL — it teaches how to think about any quasi-judicial decision. It does not contain case-specific content (parking, building lines, etc.). Case-specific content stays in the content checklists.
+
+**Applied to:**
+- `docs/decision-methodology.md` — new document
+- `lessons.py` — new function `get_methodology_summary()` injected into block-yod prompt
+- `block_writer.py` — new `{methodology_guidance}` placeholder in block-yod prompt
+- `.claude/agents/legal-writer.md` — restructured block-yod workflow to follow methodology stages
+- `.claude/agents/legal-qa.md` — new check #7 (methodology compliance)
+
+### 18. "Answer All Claims" Made Flexible
+
+**Problem:** The block-yod prompt hardcoded "answer every claim individually" and the QA check enforced it. But Dafna sometimes bundles weak claims, skips irrelevant ones, and focuses on what matters.
+
+**Fix:**
+- Block-yod prompt changed from "חובה לענות על כל אחת" to flexible handling: address substantive claims; bundle [bundle]; skip [skip]
+- Chair can mark claims in `chair_directions` as bundle or skip
+- QA check #3 updated to respect these markings
+- Methodology teaches WHEN to address individually vs. bundle vs. skip (methodology §ו)
+
+### 19. Source Library Established
+
+Downloaded and converted to text 5 authoritative sources for the methodology:
+- `docs/sources/fjc-judicial-writing-manual-1991.txt` (13,567 words)
+- `docs/sources/fjc-judicial-writing-manual-2nd-ed-2020.txt` (15,912 words)
+- `docs/sources/garner-legal-writing-plain-english.txt` (97,475 words)
+- `docs/sources/posner-how-judges-think.txt` (156,789 words)
+- `docs/sources/scalia-garner-making-your-case.txt` (54,683 words)
+Total: ~340,000 words of source material.
+
+Intermediate extraction documents also saved:
+- `docs/fjc-principles-extraction.md` — 38 principles from FJC
+- `docs/garner-methodology-extraction.md` — ~50 principles from Garner/Scalia