Skill: redkiwi1688-prog/construction-claim-strategy (version 1.7.6)

--- name: construction-claim-strategy description: Strategic planning framework for construction claim responses — plan direction, scope, arguments, and disclosure strategy BEFORE selecting clauses or drafting. Covers situation assessment, scope control, direction decisions, argument ranking, disclosure control, response architecture, and risk assessment for EOT, delay, disruption, variation, and payment claims under PSSCOC, FIDIC, NEC, SIA, and bespoke forms. Includes practical checklists, quantum calculation methods, ADR strategies, delay analysis methods, concurrent delay, disruption claims, arbitration tactics, expert engagement, notice compliance, and legal precedent guidance. --- # Construction Claim Strategy **Strategic planning framework for construction claim responses.** Plan your direction, scope, arguments, and disclosure strategy **before** selecting clauses or drafting correspondence. --- ## Why use this? - Stop jumping straight to clause selection — plan the strategy first. - Rank arguments by strength (Textual Interpretation is strongest). - Control what to disclose precisely, keep general, or defer. - Choose proven response structures. - Avoid common mistakes that weaken your position. --- ## Who this is for - Contract managers - Claims consultants - Quantity surveyors - Commercial managers - Construction lawyers - Anyone preparing responses to claims or formal queries under construction contracts --- ## What this skill does Use this tool to systematically work through 7 key dimensions: 1. **Situation Assessment** — Understand exactly what you are responding to. 2. **Scope Control** — Decide what to address and what to avoid volunteering. 3. **Direction Decision** — Choose primary and fallback arguments, and what to avoid. 4. **Argument Strategy** — Select the strongest type of argument available. 5. **Disclosure Control** — Decide what to state precisely, keep general, or defer. 6. **Response Architecture** — Choose the most effective structure for your reply. 7. **Risk Assessment** — Identify counter-arguments, weak points, and timing risks. Plus **practical tools and reference guides** covering: - Record keeping checklists - Claim preparation checklists (adjudication & arbitration) - Notice requirements compliance - Expert engagement guidance - ADR strategy (negotiation, mediation, adjudication, arbitration) - Concurrent delay strategic approach - Disruption claims strategy - Delay analysis methods (As-Planned vs As-Built, TIA, Collapsed As-Built, Windows) - Arbitration tactics and prolongation strategies - Quantum calculation worked examples (Eichleay, Hudson, Emden, Measured Mile, Actual Cost, Total Cost) - Legal precedents overview (Prevention Principle, Common Law vs Civil Law) - Common pitfalls and how to avoid them - Risk assessment framework --- ## Supported contract forms Works with any construction contract form: - PSSCOC (Construction Works / D&B) - FIDIC (Red, Yellow, Silver, Emerald) - NEC (NEC3, NEC4) - SIA Conditions - JCT - Bespoke contract conditions --- ## Working out the actual deadline Most construction claim responses are time-bound. Before using this skill, identify the actual calendar deadline for your response. For Singapore matters under the Building and Construction Industry Security of Payment Act (SOPA), or for contracts using calendar-day notice periods (PSSCOC, SIA, FIDIC, NEC), the deadline calculation is not just "today + N days". It must account for: - **Calendar-day counting** — Saturdays count; Sundays and public holidays generally do not, per s.50(a) of the Interpretation Act - **In-lieu Mondays** where a public holiday falls on a Sunday - **Ad-hoc declared holidays** (e.g. Polling Day) which are not in the standard gazetted list The companion skill **construction-law** includes a Singapore SOPA deadline calculator that handles these rules. Calculate the actual deadline there first, then provide the resulting date when prompted by this skill. If your contract is governed by a different jurisdiction, apply the equivalent local rule. Do not assume "calendar day" means simple date arithmetic — it almost never does. --- ## Start here ### Quick Reference (all strategy patterns) ```bash python3 scripts/strategy_advisor.py --reference ``` Outputs all argument types, disclosure levels, response patterns, scope control rules, and risk checklists in one view. ### Interactive Strategy Session (Recommended) ```bash python3 scripts/strategy_advisor.py ``` The wizard walks you through all 7 dimensions and produces a structured strategy report. ### Non-Interactive (from JSON) ```bash python3 scripts/strategy_advisor.py --file strategy_input.json --output strategy_report.md ``` ### Save Strategy for Reuse ```bash python3 scripts/strategy_advisor.py --save-strategy my_strategy.json ``` --- ## Examples The `examples/` folder contains a worked scenario demonstrating the full 7-Dimension workflow: | File | Description | |------|-------------| | `strategy_input.json` | Sample JSON input — PSSCOC 2014 (7th Edition) EOT scenario | | `strategy_report_sample.md` | Generated strategy report from the above input | **Note:** The example uses **PSSCOC 2014** clause references (Clauses 12.5, 14.2(m), 14.2(n), 22.1(h), 22.1(i), 14.3, 23.1). The **7-Dimension methodology itself is contract-form neutral** — it applies equally to FIDIC, NEC, SIA, JCT, and bespoke contracts. Future versions will include additional worked examples for other contract forms. --- ## Key Concepts ### Argument Strength Ranking 1. **Textual Interpretation** (Strongest) — Argue from the actual wording of the relevant clause in the Contract. 2. **Factual Distinction** (Strong) — Show that the facts fall outside the clause's scope or trigger conditions. 3. **Concede-then-Distinguish** (Moderate-Strong) — Acknowledge the normal case, then distinguish the current situation. 4. **Implied Terms** (Weakest) — Use only as a last resort when no express clause wording supports the position. ### Disclosure Control Levels | Level | Use for | |-------|---------| | **State Precisely** | Clause references, formal correspondence, key dates, and legal reasoning | | **Keep General** | Operational context and high-level details | | **Defer** | Detailed quantification and supporting analysis | ### Recommended Response Patterns - **Standard Query Response** — acknowledge, pivot, argue, reserve, close - **Risk Allocation Rebuttal** — concede ordinary application, distinguish, factual support, legal conclusion, mitigation evidence, close cooperatively - **Chronology-Based Response** — state known facts, flag pending items, commit to supplement, reserve - **Cost / Quantum Claim Response** — contractual basis, heads of claim, ongoing assessment, commit to detailed breakdown, reserve - **Reservation of Rights Closing** — always recommended ### Scope Control Rules 1. **Limit to letter** — respond only to what was asked; do not volunteer unrequested information. 2. **Preserve future claims** — use "reserves its position" and "without prejudice" language. 3. **Keep operational details general** — do not name specific zones or quantities prematurely. ### Common Anti-Patterns to Avoid - ❌ Citing the wrong clause (e.g., a clause for other contractors when the Employer caused the issue) - ❌ Leading with "the clause doesn't apply" — this antagonises the other party - ❌ Volunteering information about topics not yet raised - ❌ Naming specific zones/quantities before they are finalised - ❌ Reaching for implied terms when express clause text supports your case - ❌ Hedging dates that have formal letter references behind them - ❌ Quantifying costs before records are complete --- ## How to use ### CLI options ``` usage: strategy_advisor [-h] [--file INPUT_JSON] [--output FILE] [--format {md,txt}] [--save-strategy PATH] [--reference] [--version] Strategy Advisor — Strategic planning framework for construction claim responses. Plan your direction, scope, and argument strategy BEFORE selecting clauses. options: -h, --help show this help message and exit --file INPUT_JSON Non-interactive: read strategy inputs from a JSON file. --output, -o FILE Write report to file instead of stdout. --format, -f {md,txt} Output format (default: md). --save-strategy PATH Save the strategy data as JSON for reuse. --reference Print all reference tables (argument types, patterns, etc.) and exit. --version show program's version number and exit ``` ### Required JSON keys (for `--file` mode) The following 6 keys are **required** in the input JSON. If any are missing, the tool exits with a clear error listing what’s needed. | Key | Description | |-----|-------------| | `situation_type` | What you’re dealing with (e.g. “Responding to a rejection of our claim”) | | `other_side_position` | The other party’s stated position | | `trigger_event` | Key facts / what triggered this response | | `primary_argument` | Your primary contractual argument | | `chosen_argument_type` | Argument type (e.g. “Textual Interpretation”) | | `chosen_pattern` | Response architecture pattern (e.g. “Risk Allocation Rebuttal”) | All other keys are optional — the tool fills empty fields gracefully. See `examples/strategy_input.json` for a complete example with all 21 supported keys. ### Commands ```bash # Show all reference tables python3 scripts/strategy_advisor.py --reference # Run interactive wizard python3 scripts/strategy_advisor.py # Non-interactive from JSON python3 scripts/strategy_advisor.py --file input.json --output report.md # Save strategy for reuse python3 scripts/strategy_advisor.py --save-strategy strategy.json ``` --- ## Reference Library All reference documents are in the `references/` folder. These are standalone reading material for human use — the `strategy_advisor.py` script does not load them at runtime. | Document | Description | |----------|-------------| | `seven_dimensions_guide.md` | Full guide to the 7-Dimension framework | | `argument_ranking_guide.md` | Detailed argument types with examples | | `worked_examples.md` | 4 complete worked strategy examples (Variation, EOT, Disruption, Combined) | | `delay_analysis_study_guide.md` | Comprehensive delay analysis study guide — SCL Protocol 22 principles, 7 analysis methods, concurrent delay, pacing, float, disruption, force majeure, case law | | `quantum_worked_examples.md` | 8 quantum calculation examples (Eichleay, Hudson, Emden, Measured Mile, Actual Cost, Total Cost) | | `adr_overview.md` | ADR methods comparison and strategy recommendations | | `arbitration_tactics.md` | Arbitration tactics and prolongation claim strategies | | `concurrent_delay.md` | Concurrent delay — strategic approach within the 7-Dimension framework | | `disruption_claims.md` | Disruption claims strategy — Common Law vs Civil Law | | `delay_analysis_methods.md` | Delay analysis methods — strategic overview | | `legal_precedents.md` | Legal precedents and the Prevention Principle | | `notice_requirements_checklist.md` | Notice compliance checklist | | `expert_engagement.md` | Expert engagement tips and best practices | | `record_keeping_checklist.md` | Printable record keeping checklist | | `claim_preparation_checklist.md` | Claim preparation checklist for adjudication & arbitration | | `common_pitfalls.md` | 10 most common claim pitfalls and how to avoid them | | `risk_assessment_framework.md` | Expanded risk assessment categories and practical questions | | `response_template.md` | Letter template mapping strategy to formal response | | `quick_reference_card.md` | One-page desk reference card | | `blank_worksheet.md` | Printable blank 7-Dimension worksheet | | `training_guide.md` | Workshop-ready training material | | `strategy_patterns.md` | All strategy patterns reference | --- ## How to use with the construction-law companion skill This skill is designed to pair with **construction-law**, which handles clause analysis, notice drafting, and deadline calculation. The typical end-to-end workflow uses both skills in sequence: 1. **Identify the applicable clause and notice period** — use construction-law to look up the relevant contract clause (e.g. EOT notice provision, SOPA payment response window) and the prescribed time limit. 2. **Calculate the actual deadline** — use construction-law’s SOP calculator (or its equivalent for your contract form) to compute the calendar date, accounting for weekends, public holidays, and statutory roll-forward rules. Do not rely on simple date arithmetic. 3. **Plan the response strategy** — use this skill to work through the 7 strategy dimensions. Pass the calculated deadline as the `response_deadline` input. 4. **Draft the response** — return to construction-law for clause-level drafting and formal correspondence templates, using the strategy from step 3 as input. Keeping strategy and execution in separate skills produces more commercially realistic outputs than trying to combine them. Each skill stays focused on what it does well: this one decides the direction; construction-law executes the analysis and drafting. --- ## Requirements - Python 3.10+ - Standard library only — no third-party dependencies ## Tests ```bash python3 -m unittest tests.test_smoke ``` --- ## Security & Safety - ✅ No network access - ✅ No external calls - ✅ No subprocess execution - ✅ No dynamic code loading - ✅ No telemetry: this tool does not collect or transmit usage data - ✅ Safe for use with confidential project information - ✅ **Safe to install and use** 🛡️ ### Files written This tool writes files **only** when you pass explicit flags: | Flag | What is written | Format | |------|----------------|--------| | `--output FILE` | Strategy report | UTF-8 (Markdown or plain text) | | `--save-strategy PATH` | Strategy data for reuse | UTF-8 JSON | If neither flag is provided, output is printed to stdout. No files are created, modified, or read beyond the `--file` input (when given). --- ## Changelog ### v1.7.6 (May 2026) - **Docs:** Added "Working out the actual deadline" section — explains calendar-day counting, s.50(a) roll-forward, ad-hoc holidays; points users to construction-law SOP calculator before running strategy - **Docs:** Replaced "Companion skill" section with "How to use with construction-law" — 4-step end-to-end workflow (identify clause → calculate deadline → plan strategy → draft response) - **Wizard:** Response deadline prompt sharpened to nudge toward specific calendar dates and reference the SOP calculator - **Design decision:** No cross-skill code coupling. Date math stays in construction-law; strategy planning stays here. Skills are paired via documentation, not imports. ### v1.7.5 (May 2026) - **Security:** Sanitised test docstrings and comments — removed function-call patterns (e.g. `compile(...)`) that ClawHub static analysis flagged as `suspicious.dynamic_code_execution`. The actual detection logic uses `ast.parse` and was never affected; the scanner was pattern-matching against English text in comments. ### v1.7.4 (May 2026) - **Security:** Replaced string-grep forbidden-imports check with `ast.parse` tree-walking — properly catches `compile(...)`, `exec(...)`, `eval(...)` regardless of whitespace or indirection; no longer false-positives on comments, docstrings, or strings containing those words ### v1.7.3 (May 2026) - **Security:** Rewrote `test_smoke.py` to avoid `subprocess.run()` entirely — now imports `main()` directly and patches `sys.argv`. Resolves ClawHub ClawScan `suspicious.dynamic_code_execution` false positive on the test file - **Security:** Tightened forbidden-imports list: `urllib.request`/`urllib.error` (not blanket `urllib`), added `importlib`, `pickle`, `marshal`, `compile(` - **Performance:** Tests now run in ~0.01s (was ~0.2s with subprocess overhead) ### v1.7.2 (May 2026) - **Fix:** Interactive mode now wraps file writes (`--output`, `--save-strategy`) with friendly error messages (consistent with non-interactive mode) - **Added:** Required-key validation for `--file` JSON input — missing keys produce a clear error listing what's needed, instead of empty fields - **Added:** `_safe_write` helper — unified error handling for all file output paths - **Docs:** Added `--help` output to SKILL.md so users can evaluate CLI flags without installing - **Docs:** Added explicit "No telemetry" statement in Security section - **Docs:** Added "Files written" section documenting exactly what is written and when - **Docs:** Documented the 6 required JSON keys for `--file` mode - **Docs:** Changed test instructions to recommend `python3 -m unittest` (stdlib) over `pytest` ### v1.7.1 (May 2026) - **Security:** Added `test_no_forbidden_imports` — enforces the "no network / no subprocess" claim at test time by scanning for forbidden imports (subprocess, socket, requests, urllib, etc.) - **Compatibility:** Updated Python requirement from 3.6+ to 3.10+ (reflects what is actually tested) ### v1.7.0 (May 2026) - **Changed:** Replaced example scenario with a realistic PSSCOC EOT case (Contractor responding to SO rejection under Clause 13.2) - **Changed:** `strategy_input.json` rewritten with correct flat-key schema matching all 7 dimensions - **Changed:** `strategy_report_sample.md` regenerated from actual script output (not hand-written) - **Changed:** Improved test docstrings and header matching ### v1.6.1 (May 2026) - **Added:** JSON input validation for `--file` mode — checks file exists, valid JSON, root is a dict; warns on unrecognised keys (typo protection) - **Added:** File I/O error handling — friendly messages for missing files, permission errors, and malformed JSON (no raw tracebacks) - **Removed:** Dead code (`_prompt_yesno` function was defined but never called) ### v1.6.0 (May 2026) - **Added:** `examples/strategy_input.json` and `examples/strategy_report_sample.md` — preview output before installing - **Added:** `tests/test_smoke.py` — smoke test covering `--reference`, `--file`, and `--version` modes - **Added:** `LICENSE` file (MIT-0) shipped at package root - **Added:** Requirements section in SKILL.md (Python 3.6+, stdlib only) - **Added:** Tests section in SKILL.md - **Changed:** Vocabulary normalisation — replaced contract-form-specific terms ("Authority", "Engineer") with neutral language ("certifier", "the other party") for consistent applicability across PSSCOC, FIDIC, NEC, SIA, JCT, and bespoke contracts - **Changed:** SKILL.md clarifies that `references/` is human reading material, not loaded by the script at runtime - **Fixed:** Removed stale reference to `construction_law.py` in module docstring - **Fixed:** Removed dead conditional branch in title block of `generate_report` ### v1.5.0 (May 2026) - **Added:** Delay Analysis Study Guide — comprehensive reference covering SCL Protocol 22 Core Principles, 7 delay analysis methods (incl. Retrospective Longest Path), negative float & EOT entitlement, concurrent delay (Malmaison, North Midland, City Inn), pacing delays, disruption causation (Walter Lilly test), force majeure vs hardship, COVID-19 lessons, 15 key cases, and full definitions glossary - Sanitised from project-specific study guide; all generic content with public case law citations - Total reference documents: 22 ### v1.4.0 (May 2026) - **Major expansion:** Integrated full Construction Claim Strategy Practical Tools Guide v1.4 - Added: Notice Requirements Checklist - Added: Expert Engagement Tips - Added: Legal Precedents guide (Prevention Principle, Common Law vs Civil Law) - Added: Concurrent Delay — Strategic Approach - Added: Disruption Claims Strategy (with Common Law vs Civil Law comparison) - Added: Delay Analysis Methods — Strategic Overview (As-Planned vs As-Built, TIA, Collapsed As-Built, Windows) - Added: Arbitration Tactics & Prolongation Claim Strategies - Added: ADR Overview with Adjudication vs Arbitration detailed comparison - Added: Quantum Calculation Worked Examples (8 examples: Eichleay, Hudson, Emden, 2× Measured Mile, Actual Cost, Productivity Loss, Total Cost) - Added: Common Claim Pitfalls (10 pitfalls with fixes) - Added: Risk Assessment Framework (expanded categories and practical questions) - Added: Record Keeping Checklist (printable) - Added: Claim Preparation Checklist (printable, adjudication & arbitration) - Total reference documents: 21 ### v1.3.0 (May 2026) - Added argument ranking guide, seven dimensions guide, worked examples - Added response template, quick reference card, blank worksheet - Added training guide and strategy patterns ### v1.1.0 (May 2026) - Fully sanitized — all examples use generic/neutral language - Improved interactive wizard with examples and input validation - Better README for public listing - Added review step before report generation ### v1.0.1 (May 2026) - Removed all project-specific references - Added disclaimer ### v1.0.0 (May 2026) - Initial release — 7 strategy dimensions - Interactive wizard mode - Non-interactive JSON mode - Reference tables dump - Strategy save/reload --- *This is a generic strategic planning tool. It does not constitute legal advice. Users should verify all information independently and seek qualified legal counsel before relying on any analysis for dispute resolution, adjudication, arbitration, or court proceedings.*

path: examples/strategy_input.json
content: {
  "situation_type": "Responding to a rejection of our claim",
  "responding_to_letters": "SO Letter ref. ABC/2025/123 dated 1 May 2026",
  "other_side_position": "SO asserts that resequencing of works to accommodate other contractors is the Contractor's risk under Clause 13.2 (Other Contractors) and rejects the EOT notice of 15 April 2026. SO seeks confirmation that no time/cost claim will follow.",
  "trigger_event": "Contractor was unable to commence Zone B works on planned date due to another contractor's late completion of preceding works. EOT notice issued 15 April 2026 within the contractual notice period. SO acknowledged receipt 17 April 2026 but did not respond on entitlement until 1 May 2026.",

  "in_scope": "Disagreement with characterisation of Clause 13.2; reservation of rights on cost; confirmation that detailed particulars will follow",
  "out_of_scope": "Quantification of cost (records still being collated); specific zones beyond Zone B; naming the other contractor",
  "future_claims_to_preserve": "Prolongation cost claim; disruption claim if records support it; any further EOT arising from the same cause",

  "primary_argument": "The delay arises from an act of the Employer (failure to coordinate other contractors and a subsequent SO instruction), not from a risk allocated to the Contractor under Clause 13.2.",
  "fallback_argument": "Even if Clause 13.2 applied in ordinary terms, the specific facts (length of delay, cause attributable to Employer's instructions to the other contractor) take this case outside the clause's ordinary scope.",
  "clauses_to_avoid": "Implied term of cooperation (express clause routes are stronger; raising implied terms would weaken the position); frustration / impossibility (disproportionate to the facts)",

  "chosen_argument_type": "Textual Interpretation (primary); Factual Distinction (fallback)",
  "argument_notes": "Clause 13.2 allocates risk for delays caused by other contractors engaged by the Employer in the ordinary course. The wording does not extend to delays caused by the Employer's own subsequent instructions varying another contractor's sequence. Fallback: the resequencing was directed by the SO's instruction dated 10 March 2026, properly characterised as an Employer's act under the EOT clause.",

  "state_precisely": "Clause references; EOT notice date (15 April 2026); SO instruction date (10 March 2026)",
  "keep_general": "Operational impact on Zone B sequencing; resource redeployment effort",
  "defer_items": "Quantum of prolongation cost; detailed delay analysis (TIA / Windows); identification of specific resources affected",

  "chosen_pattern": "Risk Allocation Rebuttal",
  "architecture_notes": "1. Acknowledge SO's letter and the ordinary application of Clause 13.2. 2. Distinguish the present facts (SO instruction, not ordinary course). 3. Apply the EOT clause (Employer's act). 4. Confirm detailed particulars and quantum to follow. 5. Reserve rights expressly. 6. Close cooperatively.",

  "counter_arguments": "SO may rely on the absence of a contemporaneous record characterising the 10 March instruction as a formal variation. SO may argue the Contractor failed to mitigate by not redeploying resources earlier.",
  "weak_points": "Records of resource redeployment cost are incomplete. The programme update reflecting the impact was issued late.",
  "timing_risks": "21-day response window is tight; substantive response must precede full quantification. Limitation period for formal claim begins to run on receipt of SO determination.",
  "response_deadline": "21 days from receipt of SO letter (approx. 22 May 2026)"
}


path: examples/strategy_report_sample.md
content: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 STRATEGY REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Generated: 2026-05-17 07:10
Strategy Advisor v1.6.1

## 1. Situation Assessment

- **Type:** Responding to a rejection of our claim
- **Other side's position:** SO asserts that resequencing of works to accommodate other contractors is the Contractor's risk under Clause 13.2 (Other Contractors) and rejects the EOT notice of 15 April 2026. SO seeks confirmation that no time/cost claim will follow.
- **Trigger:** Contractor was unable to commence Zone B works on planned date due to another contractor's late completion of preceding works. EOT notice issued 15 April 2026 within the contractual notice period. SO acknowledged receipt 17 April 2026 but did not respond on entitlement until 1 May 2026.
- **Responding to:** SO Letter ref. ABC/2025/123 dated 1 May 2026

## 2. Scope Control

- **In scope:** Disagreement with characterisation of Clause 13.2; reservation of rights on cost; confirmation that detailed particulars will follow
- **Out of scope / Do NOT volunteer:** Quantification of cost (records still being collated); specific zones beyond Zone B; naming the other contractor
- **Future claims to preserve:** Prolongation cost claim; disruption claim if records support it; any further EOT arising from the same cause

**Scope Control Checklist:**
- Limit Response to Matters Raised: Which letter(s) are we replying to? What did they specifically ask?
- Preserve Future Claims: Are we making any absolute statements that could limit future claims?
- Keep Operational Details General: Are we naming anything specific that we might need to adjust later?

## 3. Direction Decision

- **Primary argument / clause:** The delay arises from an act of the Employer (failure to coordinate other contractors and a subsequent SO instruction), not from a risk allocated to the Contractor under Clause 13.2.
- **Fallback argument / clause:** Even if Clause 13.2 applied in ordinary terms, the specific facts (length of delay, cause attributable to Employer's instructions to the other contractor) take this case outside the clause's ordinary scope.
- **Clauses to AVOID:** Implied term of cooperation (express clause routes are stronger; raising implied terms would weaken the position); frustration / impossibility (disproportionate to the facts)

## 4. Argument Strategy

- **Chosen argument type:** Textual Interpretation (primary); Factual Distinction (fallback)
- **Notes:** Clause 13.2 allocates risk for delays caused by other contractors engaged by the Employer in the ordinary course. The wording does not extend to delays caused by the Employer's own subsequent instructions varying another contractor's sequence. Fallback: the resequencing was directed by the SO's instruction dated 10 March 2026, properly characterised as an Employer's act under the EOT clause.

**Argument Types (ranked by strength):**

- Rank 1: Textual Interpretation (Strongest)
  - When: Always start here. If you can win on the text, you don't need anything else. Courts and contract administrators prefer textual arguments.
- Rank 2: Factual Distinction (Strong)
  - When: When the text is broad but the facts are extraordinary. Pairs well with textual interpretation as a 1–2 punch.
- Rank 3: Concede-then-Distinguish (Moderate-Strong)
  - When: For risk-allocation rebuttals. Never lead with 'the clause doesn't apply' — it antagonises the certifier. Concede the ordinary application first, then distinguish.
- Rank 4: Implied Terms / Prevention Principle (Weakest)
  - When: Last resort only. If you're reaching for implied terms when express clauses exist, your primary arguments are probably weak. Consider whether the claim is viable at all.

## 5. Disclosure Control

- **State precisely:** Clause references; EOT notice date (15 April 2026); SO instruction date (10 March 2026)
- **Keep general:** Operational impact on Zone B sequencing; resource redeployment effort
- **Defer to Claim Report:** Quantum of prolongation cost; detailed delay analysis (TIA / Windows); identification of specific resources affected

**Disclosure Level Reference:**
- State Precisely: Documented facts with letter references, clause numbers, legal reasoning.
  - Other contractor commenced late on [date] (ref. Contractor's letter ref. [XXX])
  - EOT clause for acts/omissions of other contractors — Clause 14.2(m)
  - Contractor's notice ref. [XXX] dated [date] issued under Clause 14.3
- Keep General: Operational details (zones, quantities), dates without written record, internal arrangements. Use general language to preserve flexibility.
  - 'multiple work areas within and outside the Site' (not Zone A, Zone B)
  - 'resequencing of works' (not specific programme activities)
  - 'approximately [date]' for verbal/informal communications
- Defer to Claim Report: Full quantification, detailed delay analysis, cost breakdown, programme impact. Reserve for the Notified Claim Report or subsequent submissions.
  - Detailed delay analysis with critical path impact
  - Cost breakdown with quantities, rates, invoices
  - Zone-by-zone production records
  - Programme comparison (baseline vs actual vs impacted)

## 6. Response Architecture

- **Chosen pattern(s):** Risk Allocation Rebuttal
- **Notes:** 1. Acknowledge SO's letter and the ordinary application of Clause 13.2. 2. Distinguish the present facts (SO instruction, not ordinary course). 3. Apply the EOT clause (Employer's act). 4. Confirm detailed particulars and quantum to follow. 5. Reserve rights expressly. 6. Close cooperatively.

**Available Response Patterns:**

- **Standard Certifier Query Response**
  - Step 1: Acknowledge the certifier's position / question
  - Step 2: Pivot to Contractor's primary contractual reliance
  - Step 3: State primary argument (textual interpretation)
  - Step 4: Reserve fallback clause(s) without elaborating
  - Step 5: Close cooperatively
  - When: Default pattern for responding to certifier queries. Works for most items in a request-for-information letter.

- **Risk Allocation Rebuttal (Concede-then-Distinguish)**
  - Step 1: Concede the ordinary application of the risk clause
  - Step 2: Distinguish the extraordinary facts of THIS case
  - Step 3: Provide factual support (before/after, what changed)
  - Step 4: State legal conclusion (clause covers X, this is Y)
  - Step 5: Show mitigation evidence (demonstrates good faith)
  - Step 6: Close cooperatively — accept ordinary risk, maintain this is extraordinary
  - When: When the certifier points to a specific risk-allocation clause (e.g., a clause allocating interface risk to the Contractor) and says the risk is yours. Never lead with 'the clause doesn't apply'.

- **Chronology / Details Response**
  - Step 1: State what is known with exact dates and references
  - Step 2: Flag items still being compiled (don't hedge documented facts)
  - Step 3: Commit to supplementing in the Notified Claim Report
  - Step 4: Reserve right to provide further details
  - When: When asked for chronology, details, or documentary evidence. Provide what you have, hedge only what's genuinely uncertain, defer the rest.

- **Cost Claim Response (Pre-Quantification)**
  - Step 1: Identify the contractual basis for cost recovery (e.g., Cl. 63.1)
  - Step 2: List heads of claim without quantifying
  - Step 3: State that the disruption is ongoing / costs are being assessed
  - Step 4: Commit to detailed breakdown in the Notified Claim Report
  - Step 5: Reserve right to supplement
  - When: When asked for cost breakdowns before you're ready to quantify. Name the heads of claim to show awareness, but don't lock in numbers prematurely.

- **Reservation of Rights Closing**
  - Step 1: State that submission is on an interim / without prejudice basis
  - Step 2: Reserve all rights, remedies, claims, and entitlements
  - Step 3: Under the Contract, at law, or otherwise
  - Step 4: Commit to cooperation
  - When: Always. Every substantive response should end with a reservation.

## 7. Risk Assessment

- **Expected counter-arguments:** SO may rely on the absence of a contemporaneous record characterising the 10 March instruction as a formal variation. SO may argue the Contractor failed to mitigate by not redeploying resources earlier.
- **Known weak points:** Records of resource redeployment cost are incomplete. The programme update reflecting the impact was issued late.
- **Timing risks:** 21-day response window is tight; substantive response must precede full quantification. Limitation period for formal claim begins to run on receipt of SO determination.
- **Response deadline:** 21 days from receipt of SO letter (approx. 22 May 2026)

**Risk Checklist:**
- Counter-Arguments
  - What will the other party argue in response?
  - Which clauses might they cite to rebut our position?
  - Are there any contractual provisions that explicitly allocate this risk to us?
  - Can they argue we failed to mitigate?
- Weak Points
  - Is our notice timing vulnerable? (Late notice = potential time-bar.)
  - Are there gaps in our contemporaneous records?
  - Did we create any inconsistencies in prior correspondence?
  - Are we relying on verbal communications without written confirmation?
- Timing Risks
  - What is the response deadline?
  - Is the disruption still ongoing? (Affects quantification.)
  - Are there parallel claims or notices that interact with this one?
  - Could delay in responding weaken our position or trigger time-bar arguments?
- Disclosure Risks
  - Are we volunteering anything the other side hasn't asked about?
  - Could any statement be used against us in a future dispute?
  - Are we prematurely quantifying before records are complete?
  - Are we naming specifics (zones, dates, quantities) we might need to change?

────────────────────────────────────────────────────
Generated by Strategy Advisor v1.6.1
This is a strategic planning aid only. It is not legal advice.
────────────────────────────────────────────────────

path: references/adr_overview.md
content: # ADR in Construction Claims — Overview & Strategies

Alternative Dispute Resolution (ADR) provides ways to resolve disputes without going to full court litigation. Choosing the right method depends on your goals: speed, cost, finality, cash flow, and relationship preservation.

---

## ADR Methods Comparison

| Method | Description | Binding? | Speed | Cost | Best Used When |
|--------|-------------|----------|-------|------|---------------|
| **Negotiation** | Direct discussion between parties | No | Fast | Low | Early stage, good relationship |
| **Mediation** | Neutral facilitator helps reach settlement | No (usually) | Fast | Low–Medium | Preserve relationship, complex issues |
| **Adjudication** | Fast interim decision by adjudicator | Yes (usually interim/temporary) | Very Fast | Medium | Cash flow or interim relief needed |
| **Arbitration** | Private tribunal makes final decision | Yes (final) | Medium–Slow | High | Final resolution, international disputes |
| **Litigation** | Court proceedings | Yes (final) | Slow | High | Last resort, complex legal points |

---

## ADR Strategy Recommendations

1. **Start with negotiation** where possible — many disputes can be resolved early if approached professionally
2. **Use mediation** when preserving the commercial relationship is important or when issues are complex
3. **Consider adjudication** (where available) for fast interim cash flow or time-related decisions
4. **Choose arbitration** for final, binding resolution, especially in international projects
5. **Use litigation** generally as a last resort due to cost, time, and relationship impact

---

## Adjudication vs Arbitration — Detailed Comparison

| Aspect | Adjudication | Arbitration |
|--------|-------------|-------------|
| **Nature** | Fast interim decision | Final and binding decision |
| **Speed** | Very fast (usually 28–42 days in statutory regimes) | Slow to medium (6–24 months) |
| **Cost** | Relatively low | High |
| **Binding** | Binding until finally determined by arbitration or litigation | Final and binding |
| **Enforceability** | Enforceable in jurisdictions with statutory adjudication | Enforceable internationally (New York Convention) |
| **Right of appeal** | Limited (usually only jurisdiction or natural justice) | Limited, depends on seat of arbitration |
| **Procedure** | Relatively informal and fast | More formal, similar to litigation |
| **Evidence** | Often limited written submissions | Full hearing with witnesses and experts |
| **Relationship impact** | Can be less damaging if used early | Often more adversarial |

### When to Choose Adjudication

- Need **quick cash flow** relief
- Want to keep the project moving during dispute resolution
- Dispute is relatively straightforward
- Available under a statutory regime or contract

### When to Choose Arbitration

- Need a **final and binding** decision
- Dispute is complex, high-value, or multi-issue
- International enforceability matters
- Parties can choose arbitrators with relevant expertise

---

## Decision Guide

| Your Goal | Recommended Route |
|-----------|-------------------|
| Need money / relief quickly | **Adjudication** (if available) |
| Want a final and binding decision | **Arbitration** |
| Want to preserve commercial relationship | Start with **Negotiation → Mediation** |
| High-value, complex, international dispute | **Arbitration** |
| Domestic dispute needing fast interim relief | **Adjudication** |

---

## Common Law vs Civil Law Perspective

| Aspect | Common Law | Civil Law |
|--------|-----------|-----------|
| **Adjudication** | Very common (often statutory) | Less common (more voluntary) |
| **Arbitration** | Widely used | Very widely used |
| **Preference** | Often adjudication first, then arbitration | Tend to go straight to arbitration or mediation |
| **Statutory support** | Strong statutory regimes for adjudication | Generally rely on contractual ADR clauses |

---

*This is a generic reference guide. It does not constitute legal advice.*


path: references/arbitration_tactics.md
content: # Arbitration Tactics & Prolongation Claim Strategies

---

## Arbitration Tactics — Common Law vs Civil Law

### Common Law Arbitrations

- Heavy emphasis on **contemporaneous documents**, detailed witness statements, and expert reports
- Cross-examination is often rigorous — be prepared to defend methodology and credibility in detail
- Broader **document disclosure** is common; failure to disclose can damage credibility
- Significant reliance on **case law and precedents** in areas such as notice, prevention principle, and quantum methods
- **Strategy:** Build a document-heavy, precedent-supported case with strong expert evidence

### Civil Law / Mixed Arbitrations

- Greater emphasis on overall **fairness, good faith, and commercial equity**
- Cross-examination may be less confrontational, depending on tribunal and rules
- Disclosure is usually **narrower**
- More reliance on principles of good faith and fairness than strict precedent
- **Strategy:** Combine strong factual evidence with clear arguments on equity and the parties' reasonable expectations

---

## Comparison Table

| Aspect | Common Law Arbitration | Civil Law / Mixed Arbitration |
|--------|----------------------|------------------------------|
| Documents | Heavy reliance; broad disclosure | Narrower disclosure |
| Witnesses | Detailed statements; rigorous cross-exam | Less confrontational |
| Experts | Essential for complex claims | Important but approach may differ |
| Precedents | Key part of submissions | Persuasive but less central |
| Good faith | Developing | Central principle |
| Strategy focus | Document + precedent | Equity + evidence |

---

## Prolongation Claim Strategies in Arbitration

### Common Law Approach

- Strong focus on proving **EOT first** (critical path impact) before claiming prolongation costs
- Expect detailed scrutiny of quantum methods and baseline assumptions
- Concurrent delay arguments are common and must be addressed **proactively**
- **Strategy:** Secure the EOT foundation first, then build a well-supported prolongation claim — preferably based on actual costs with formula methods as fallback

### Civil Law Approach

- The link between EOT and prolongation costs may be assessed **more flexibly**, depending on governing law and tribunal approach
- Actual costs remain preferred, but good faith and fairness arguments may help bridge gaps in strict causation proof
- **Strategy:** Emphasise the overall impact and equity of the situation while still providing clear cost evidence

---

## Practical Recommendations

1. **Know your tribunal** — research the arbitrators' backgrounds and preferred approaches
2. **Prepare for cross-examination** — ensure witnesses and experts are thoroughly prepared
3. **Disclosure strategy** — balance completeness with risk of revealing unhelpful documents
4. **Quantum foundation** — always anchor prolongation to a clear EOT finding
5. **Address concurrent delay proactively** — don't leave it for the other side to raise
6. **Clear visuals** — timelines, charts, and cost summaries are often more effective than dense narrative

---

*This is a generic strategic guide. It does not constitute legal advice.*


path: references/argument_ranking_guide.md
content: # Argument Ranking — Detailed Guide

*Construction Claim Strategy Framework — Fully Generic*

---

## Why the Ranking Exists

Not all arguments carry the same weight. Stronger arguments are harder to rebut and more likely to be accepted by tribunals, adjudicators, and courts. Weaker arguments are easier to challenge.

Always start from the top of the ranking. Only move down when stronger options are unavailable.

---

## Rank 1: Textual Interpretation (Strongest)

**What it is:**
Argue directly from the actual words used in the Contract clause.

**Why it is strongest:**
- Based on express terms the parties agreed to.
- Most objective and difficult for the other side to dismiss.
- Tribunals and courts prefer to give effect to clear wording.

**When to use:** Whenever the wording of the clause supports your position.

**Example structure:**
> The Contract provides that the Contractor shall be entitled to [entitlement] where the Authority issues an instruction which changes the scope of the Works.
> On [date], the Authority issued Instruction No. X which required the Contractor to [specific change]. This instruction directly changed the scope.
> Accordingly, the Contractor is entitled to [relief] pursuant to the clear wording of the clause.

**Recommended disclosure level:** State Precisely — you can be confident and specific.

---

## Rank 2: Factual Distinction (Strong)

**What it is:**
Accept that the clause exists, but argue that the facts of your case fall outside the situation the clause was intended to cover.

**Why it is strong:**
Stays close to the Contract wording while showing why the clause does not apply to the current situation.

**When to use:** When the clause wording is not clearly in your favour, but the facts are materially different from what the clause contemplates.

**Example structure:**
> While the Contract contains provisions regarding [subject], those provisions are predicated on the assumption that [normal situation].
> In the present case, the situation is materially different because [key factual difference].
> Accordingly, the clause does not operate to [deny the claim / allocate risk in the way suggested].

**Recommended disclosure level:** State Precisely or Keep General — be precise on facts that support the distinction.

---

## Rank 3: Concede-then-Distinguish (Moderate-Strong)

**What it is:**
Concede that the clause would normally apply, then explain why the current situation is extraordinary or materially different.

**Why it is moderate-strong:**
Shows reasonableness (not denying the clause entirely), while still protecting your position.

**When to use:** When the clause appears to go against you at first glance, but there are good reasons why it should not apply in this specific case.

**Example structure:**
> The Contractor acknowledges that, in normal circumstances, [risk] would be allocated to the Contractor under the Contract.
> However, the present situation is materially different. The Authority [did X / failed to do Y / provided incorrect information], which fundamentally changed the nature of the risk.
> In these exceptional circumstances, it would be inconsistent with the Contract for the risk to remain with the Contractor.
> Accordingly, the Contractor is entitled to [relief].

**Recommended disclosure level:** Keep General — be careful not to over-disclose internal thinking.

---

## Rank 4: Implied Terms / Prevention Principle (Weakest)

**What it is:**
Argue that a term should be implied into the Contract, or that the Authority's actions prevented you from performing.

**Why it is weakest:**
- Implied terms are harder to prove.
- Prevention principle is heavily contested.
- Moves away from express Contract words.
- Easier for the other side to challenge.

**When to use:** Only as a last resort, when none of the stronger arguments are available.

**Example structure:**
> It is a well-established principle that a party to a contract must not do anything to prevent the other party from performing its obligations.
> In this case, the Authority's [action / inaction / instruction] had the effect of preventing the Contractor from [completing the works / mitigating losses].
> As a result, the Contractor is entitled to [relief].

**Note:** More commonly used in Common Law jurisdictions. In Civil Law systems, similar concepts exist under good faith (*bonne foi* / *Treu und Glauben*).

**Recommended disclosure level:** Keep General — these arguments are more vulnerable.

---

## How to Choose

| Rank | Argument Type | Strength | When to Use | Recommendation |
|------|---|---|---|---|
| 1 | Textual Interpretation | Strongest | Clause wording supports your position | Use first |
| 2 | Factual Distinction | Strong | Facts are materially different | Strong backup |
| 3 | Concede-then-Distinguish | Moderate-Strong | Clause appears unfavourable but facts are exceptional | Use carefully |
| 4 | Implied Terms / Prevention | Weakest | No better argument available | Last resort |

---

## Combining Arguments (Primary + Fallback)

You can and often should use a primary + fallback approach in the same response.

**Recommended structure:**
1. Lead with the strongest available argument.
2. Clearly signal the fallback.
3. Use clear paragraph breaks or numbering.

**Example — Textual Interpretation + Factual Distinction:**

> **Primary Position — Textual Interpretation**
> The Contract states that the Contractor is entitled to additional time and cost where the Authority issues an instruction which varies the Works. The Authority's Instruction dated [X] required the Contractor to [change]. This falls squarely within the wording of the clause.
>
> **Alternative Position — Factual Distinction**
> Without prejudice to the above, even if the clause were interpreted more restrictively, the facts of this case are materially different from the normal situation contemplated by the Contract. At the time of the instruction, [key fact that makes it different]. Accordingly, the clause does not operate to exclude the Contractor's entitlement.

---

## Argument Strength ↔ Disclosure Control Interaction

| Argument Type | Strength | Disclosure Level | Reason |
|---|---|---|---|
| Textual Interpretation | Strongest | State Precisely | Position is robust; confidence is high |
| Factual Distinction | Strong | State Precisely / Keep General | Precise on supporting facts |
| Concede-then-Distinguish | Moderate-Strong | Keep General | Partial concession; don't over-disclose |
| Implied Terms / Prevention | Weakest | Keep General | Vulnerable; avoid giving material to attack |

**Rule:** Stronger arguments → more precise disclosure. Weaker arguments → more general disclosure. Always apply scope control regardless.

---

*This is a workflow and analysis aid only. It does not constitute legal advice.*


path: references/blank_worksheet.md
content: # Blank Strategy Worksheet

**Construction Claim Strategy — Quick Worksheet**

**Date:** _______________
**Claim / Query Type:** _______________

---

## 1. Situation Assessment
What exactly are we responding to?

____________________________________________________________________________

## 2. Scope Control
**Must address:**

____________________________________________________________________________

**Must avoid:**

____________________________________________________________________________

## 3. Direction Decision
**Primary argument:**

____________________________________________________________________________

**Fallback argument:**

____________________________________________________________________________

**Arguments to avoid:**

____________________________________________________________________________

## 4. Argument Strategy
Chosen argument type:
☐ Textual Interpretation (Strongest)
☐ Factual Distinction (Strong)
☐ Concede-then-Distinguish (Moderate-Strong)
☐ Implied Terms (Weakest — last resort)

Reason:

____________________________________________________________________________

## 5. Disclosure Control

| Level | What to include |
|---|---|
| **State Precisely** | |
| **Keep General** | |
| **Defer** | |

## 6. Response Architecture
Chosen structure:
☐ Standard Query Response
☐ Risk Allocation Rebuttal
☐ Chronology-Based Response
☐ Cost / Quantum Claim Response

Reason:

____________________________________________________________________________

## 7. Risk Assessment
Main risks / counter-arguments:

____________________________________________________________________________

How to address them:

____________________________________________________________________________

---

**Next Step:** Use this completed worksheet to draft the formal response.

*Plan → Strategise → Draft*


path: references/claim_preparation_checklist.md
content: # Claim Preparation Checklist

Use this checklist when preparing claims for Adjudication or Arbitration. Thorough preparation significantly improves outcomes.

---

**Project:** _______________________________ **Claim Type:** _______________

## Phase 1: Strategy & Planning

- [ ] Reviewed the contract dispute resolution clause
- [ ] Completed the 7-Dimension Strategy Worksheet
- [ ] Identified the main heads of claim (EOT, disruption, variation, prolongation, acceleration)
- [ ] Decided whether to submit claims separately or combined

## Phase 2: Evidence Collection

- [ ] Compiled a clear chronology of events
- [ ] Collected and organised all relevant correspondence
- [ ] Gathered all notices with proof of submission
- [ ] Collected programme, progress, and site records
- [ ] Gathered cost and quantum supporting documents
- [ ] Identified and addressed any gaps in records

## Phase 3: Claim Development

- [ ] Prepared a clear summary of the claim
- [ ] Developed Primary and Fallback arguments
- [ ] Prepared quantum calculation with clear methodology
- [ ] Identified and prepared witnesses, if required
- [ ] Engaged experts (delay analyst, quantum expert, technical expert) if needed

## Phase 4: Risk Assessment & Review

- [ ] Conducted honest Risk Assessment of own case
- [ ] Identified likely counter-arguments from the other side
- [ ] Reviewed and strengthened weak areas
- [ ] Finalised disclosure strategy

## Phase 5: Final Preparation & Submission

- [ ] Prepared position paper / submissions
- [ ] Organised document bundle, indexed and paginated
- [ ] Prepared opening statement / summary
- [ ] Conducted internal review
- [ ] Submitted on time

## Adjudication-Specific Items

- [ ] Kept submissions concise and focused
- [ ] Prioritised speed and clarity

## Arbitration-Specific Items

- [ ] Prepared more detailed and comprehensive submissions
- [ ] Arranged witness statements and expert evidence
- [ ] Planned for possible hearings

**Prepared by:** ___________________________ **Date:** _______________

---

*This is a generic checklist. It does not constitute legal advice.*


path: references/common_pitfalls.md
content: # Common Claim Pitfalls & How to Avoid Them

Most claims fail or are significantly weakened due to **process issues** rather than weak facts.

---

## The 10 Most Common Pitfalls

| # | Pitfall | Why It's Harmful | How to Avoid |
|---|---------|-----------------|--------------|
| 1 | **Jumping straight to drafting** without proper strategy | Leads to weak arguments and poor structure | Complete the 7-Dimension Strategy Worksheet first |
| 2 | **Volunteering unrequested information** | Creates new issues or admissions the other side can exploit | Apply strict Scope Control — respond only to what was asked |
| 3 | **Using the weakest argument first** | Damages credibility from the outset | Follow the argument ranking: Textual → Factual → Concede-then-Distinguish → Implied Terms |
| 4 | **Over-disclosing sensitive information too early** | Gives the other side material to attack your position | Match disclosure level to argument strength; defer where appropriate |
| 5 | **Mixing EOT and disruption claims** without clear separation | Creates confusion and weakens both claims | Keep them clearly separated unless both are genuinely present and can be distinguished |
| 6 | **Quantifying costs or delay before records are complete** | Numbers can be attacked if not fully supported | Defer detailed quantum until records are complete |
| 7 | **Ignoring or missing contractual notice requirements** | Claim can be time-barred or rejected | Check notice provisions early in Risk Assessment; use the Notice Requirements Checklist |
| 8 | **Using a poor or aggressive tone** in correspondence | Damages commercial relationship and credibility | Use professional, factual language throughout |
| 9 | **Failing to include a reservation of rights** | Can limit future claims or entitlements | Always include a clear Reservation of Rights |
| 10 | **Not conducting honest risk assessment** before submitting | Surprised by strong counter-arguments later | Complete the Risk Assessment dimension honestly |

## Key Prevention

Complete the **7-Dimension Strategy** first and apply strict **Scope Control** and **Disclosure Control**.

---

*This is a generic reference guide. It does not constitute legal advice.*


path: references/concurrent_delay.md
content: # Concurrent Delay — Strategic Approach

Concurrent delay occurs when two or more independent delay events — typically one caused by the Contractor and one by the Employer/Authority — overlap in time and both are alleged to affect the completion date.

It is one of the most complex and disputed areas in construction claims.

---

## Why Concurrent Delay Matters Strategically

- It directly impacts **Extension of Time** entitlement and **liquidated damages** exposure
- It affects **prolongation cost claims**
- Different jurisdictions apply **different approaches**, creating strategic risk if not handled correctly
- Poor handling of concurrent delay is a common reason claims are **reduced or rejected** in adjudication and arbitration

---

## Common Approaches

### Common Law Jurisdictions

Approaches vary and may include:
- **Dominant cause** — which delay had the greater impact?
- **Apportionment** — split responsibility between the parties
- **First-in-time / prevention principle** — the first cause takes precedence

The applicable approach must be checked against the governing law and contract terms.

### Civil Law Jurisdictions

- More reliance on **good faith and fairness**
- Tribunals may look at overall impact and whether one party's actions prevented the other from mitigating delay
- Less rigid adherence to a single analysis method

---

## Strategic Recommendations — 7-Dimension Framework

### 1. Situation Assessment & Risk Assessment

- Identify all delaying events early and classify them as **Employer-caused**, **Contractor-caused**, or **neutral**
- Analyse periods of potential concurrency and document them
- Assess the risk of the other side arguing concurrency to reduce EOT or impose liquidated damages

### 2. Argument Strategy

- **Primary:** Use strong factual evidence to show Employer delay events were on the critical path and that Contractor delays did not cause overall delay
- **Fallback:** Argue for apportionment or prevention/good faith reasoning if full EOT is not accepted
- **Avoid** weak global arguments — be specific about which events caused which delay

### 3. Disclosure Control

- Be careful with full programme disclosure if it shows Contractor-caused delays — seek legal advice on what must be disclosed
- Clearly separate Employer-caused delay from Contractor-caused delay in submissions

### 4. Response Architecture

- **Proactively** address potential concurrency arguments rather than waiting for the other side to raise them
- Use clear diagrams or summaries showing critical path and overlapping periods

---

## Practical Tips

- Maintain detailed and updated programmes throughout the project
- Use a consistent delay analysis method and be prepared to justify it
- In international arbitration, be ready to explain which approach should apply based on governing law and contract
- Consider engaging a delay expert early if concurrency is likely to be a major issue

---

*This is a generic strategic guide. It does not constitute legal advice.*


path: references/delay_analysis_methods.md
content: # Delay Analysis Methods — Strategic Overview

Delay analysis is the process of investigating the causes and effects of delays on a construction project. The method chosen can significantly impact the strength of an Extension of Time or prolongation claim.

---

## Main Delay Analysis Methods

### As-Planned vs As-Built

Compares the original baseline programme with actual progress.

- **Strengths:** Simple, easy to understand
- **Weaknesses:** Can be challenged if the baseline was unrealistic
- **Best for:** Simple delay scenarios with a clear baseline

### Time Impact Analysis (TIA)

Adds delay events one by one to an updated programme to show the impact at the time they occurred.

- **Strengths:** Generally considered robust and widely accepted
- **Weaknesses:** Requires good contemporaneous programme records; can be complex
- **Best for:** Complex projects with multiple delay events

### Collapsed As-Built / But-For Analysis

Removes delay events from the as-built programme to show what the completion date would have been "but for" those events.

- **Strengths:** Uses actual as-built data
- **Weaknesses:** Retrospective; can be challenged on assumptions about what "would have" happened
- **Best for:** Post-completion analysis

### Windows Analysis

Divides the project into time windows and analyses delays within each window.

- **Strengths:** Useful for complex projects with multiple issues; can isolate periods of delay
- **Weaknesses:** Complex; window boundaries can be disputed
- **Best for:** Large, complex projects with multiple overlapping events

---

## Method Comparison

| Method | Complexity | Reliance on Programme | Timing | Acceptance |
|--------|------------|----------------------|--------|------------|
| As-Planned vs As-Built | Low | Baseline + As-built | Post-completion | Moderate |
| Time Impact Analysis | High | Updated programmes | Prospective | High |
| Collapsed As-Built | Medium | As-built | Retrospective | Moderate-High |
| Windows Analysis | High | Updated programmes | Either | High |

---

## Strategic Considerations — Common Law vs Civil Law

### Common Law

- Often a strong preference for methods that demonstrate **causation at the time the delay occurred** (e.g. TIA)
- Tribunals may expect a clear link between specific events and critical path impact

### Civil Law

- The approach may be more **flexible and pragmatic**
- Tribunals may focus on overall fairness, good faith, and whether the claimed events genuinely impacted progress
- Analysis must still be logical and supported by contemporaneous records

---

## Strategic Recommendations

1. Choose a method appropriate to the **project complexity** and **quality of available records**
2. Be **consistent** — changing methods mid-claim without good reason damages credibility
3. In common law jurisdictions, be prepared to defend the method by reference to established practice
4. In civil law or international arbitration, focus on demonstrating overall impact and fairness while still providing clear analysis
5. **Maintain and update the programme contemporaneously** — this is the foundation of credible delay analysis

---

*This is a generic strategic guide. It does not constitute legal advice.*


path: references/delay_analysis_study_guide.md
content: # Delay Analysis Study Guide for Contract Managers

Practical study notes for delay analysis in construction and infrastructure projects.

**Sources:** SCL Delay and Disruption Protocol 2nd Edition (February 2017) + Rider 1 (February 2022), AACEi Recommended Practice 29R-03, published case law.

> **Caution:** Always confirm which contract edition applies before relying on any clause references. This guide does not constitute legal advice.

---

## Part 1: What Is Delay Analysis?

Delay analysis is the process of identifying what caused a project delay, who is responsible, and what the time/cost consequences are.

It answers two distinct questions:
1. **Is the contractor entitled to an Extension of Time (EOT)?** — a time question
2. **Is the contractor entitled to compensation?** — a money question

These are linked but separate inquiries (see SCL Principle 12).

---

## Part 2: Key Concepts

### 2.1 Delay vs Disruption vs Prolongation

| Concept | What It Is | Result | Claim Type |
|---------|-----------|--------|------------|
| **Delay** | Activity takes longer than planned or starts late | Critical path pushed → later completion | EOT (time) |
| **Disruption** | Reduced productivity / efficiency — more resources needed per unit of work | Additional cost, may or may not affect completion date | Money (cost) |
| **Prolongation** | Extended presence on site due to delay | Additional preliminaries, site overheads | Money (cost) |

**Key distinction:** You can have disruption WITHOUT delay (if the affected activity is not on the critical path). You can also have delay WITHOUT disruption (if the activity simply stops).

### 2.2 Types of Delay

| Type | Who Bears Risk | EOT? | Compensation? |
|------|---------------|------|---------------|
| **Employer Risk Event** (late instructions, design changes, site access) | Employer | ✓ Yes | ✓ Yes (usually) |
| **Neutral/Excusable Event** (exceptionally adverse weather, force majeure) | Shared | ✓ Yes | ✗ Usually not |
| **Contractor Risk Event** (poor planning, resource shortages) | Contractor | ✗ No | ✗ No |
| **Concurrent Delay** (employer + contractor delays at same time) | Complex | ✓ Yes (SCL view) | Debatable — see 2.4 |

**Excusable vs Compensable:** An excusable delay relieves the contractor from LD (i.e. EOT). A compensable delay additionally entitles the contractor to money. All compensable delays are excusable, but not all excusable delays are compensable.

### 2.3 Critical Path & Float

The **critical path** is the longest sequence of activities that determines the project completion date. Only delays to activities on the critical path will actually delay the project.

**Float** = the time an activity can slip without affecting the critical path.

**Who owns the float?** The SCL Protocol says float should generally be available to the project (not owned by either party) unless the contract says otherwise.

#### Understanding Float Types

| Float Type | What It Means | EOT Implication |
|-----------|---------------|-----------------|
| **Positive Float** | Activity has buffer — can slip without delaying completion | Employer delay may consume float before affecting critical path |
| **Zero Float** | Activity is on the critical path — any delay directly delays completion | Every day of employer delay = one day of EOT entitlement |
| **Negative Float** | Projected completion already exceeds contract completion date | EOT can still be claimed for employer risk events — see below |

#### Negative Float & EOT Entitlement

Negative float does **NOT** bar an EOT claim. Negative float occurs when the programme's projected completion date already exceeds the contract completion date, even before a new delay event arises. This is common on complex infrastructure projects.

The SCL Protocol (Principles 6, 7 and 10) requires that each delay event be assessed for its own **incremental impact** on the critical path. If an employer risk event extends the completion date by a further 2 weeks — even where the programme already shows negative float — that 2-week impact remains an employer-caused delay.

**Three practical scenarios:**

- **Scenario 1 — Negative float from contractor delays:** The contractor still claims EOT for any employer risk event's incremental impact. Time Impact Analysis (TIA) handles this best.
- **Scenario 2 — Negative float from employer delays:** This strengthens the EOT position. The employer delay events that drove the programme into negative float are themselves grounds for EOT.
- **Scenario 3 — Concurrent delay with negative float:** The most complex scenario. Under the *Malmaison* approach, the contractor still gets EOT to protect against LDs but may not recover prolongation costs for the concurrent period.

**Bottom line:** Float status (positive, zero, or negative) does not determine EOT entitlement. It is the **cause and incremental impact** of each delay event that matters.

#### Terminal Float

Terminal float is the gap between the contractor's planned completion date and the contract completion date.

Per SCL Protocol Principle 13 (Early Completion): if the contractor planned to finish early and an employer delay consumes that terminal float, the contractor may still have a **compensation claim** for disruption to its planned programme — even if the contract date has not been breached.

### 2.4 Concurrent Delay

**SCL Protocol position:** Where employer delay is concurrent with contractor delay → contractor gets EOT (to protect from LD). But contractor may **NOT** recover prolongation costs for the concurrent period. This is the *Malmaison* approach (*Henry Boot v Malmaison* [1999]).

#### Three Critical Nuances

**Nuance 1 — True Concurrent vs Sequential Concurrent**

True concurrent delay means two delay events start and end at the same time, both independently affecting the critical path. Sequential concurrent delay means the events overlap but do not start together. Tribunals apply the *Malmaison* approach more readily to true concurrent delay; sequential concurrent delay is often analysed by isolating each event's impact via TIA.

**Nuance 2 — Contractual Allocation**

The *Malmaison* default can be contracted out. In *North Midland Building Ltd v Cyden Homes Ltd* [2018] EWCA Civ 1744, the English Court of Appeal upheld a contract clause that expressly excluded EOT where contractor delay was concurrent with employer delay. Parties are free to allocate the risk of concurrent delay as they choose.

**Practical action:** Read the EOT clause carefully. Some bespoke amendments may include a "contractor caused concurrent delay" carve-out that strips the contractor of EOT entitlement. If found, raise this with management early — it is a major risk allocation issue.

**Nuance 3 — Apportionment Approach**

In *City Inn Ltd v Shepherd Construction Ltd* [2010] CSIH 68, the Scottish courts took a different view: where it is impossible to say which delay was "dominant", the tribunal can apportion the EOT between employer and contractor causes (e.g. 60/40). This approach has not been adopted in English courts but remains influential and may be argued in arbitration.

**Practical tip:** Always try to separate and identify each delay cause individually. Strong contemporaneous records are the best defence against concurrent delay arguments.

### 2.5 Pacing Delays

**What is pacing?** Pacing occurs when one party (usually the contractor) deliberately slows non-critical work to match the pace of the other party who is causing the critical path delay. It is a rational business decision.

**Why it matters:** Pacing is **not** a contractor culpable delay. But it is frequently mischaracterised as one — especially in retrospective analysis.

**How to prove pacing:**
- Issue contemporaneous notice that you are pacing in response to the specific employer delay event
- Identify the employer delay event you are pacing (cite notice/event reference)
- Show the activity being paced was not on the critical path but for the employer delay
- Demonstrate you had the resources and capability to proceed at planned pace
- Confirm pacing did not extend the project completion date beyond the employer delay impact

**Quick test:** "Could I have proceeded at planned pace if the employer delay event had not occurred?" If YES → pacing. If NO → genuine contractor delay.

---

## Part 3: The SCL Protocol — 22 Core Principles

> References are to the SCL Delay and Disruption Protocol, 2nd Edition (February 2017), as supplemented by Rider 1 (February 2022). Rider 1 added guidance on COVID-19, BIM, concurrent delay analysis, and the relationship between EOT and compensation.

| # | Principle | Key Point |
|---|-----------|-----------|
| 1 | **Programme & Records** | Maintain a proper baseline programme and comprehensive contemporaneous records. No records = no claim. |
| 2 | **Purpose of EOT** | EOT relieves the contractor from LD liability and preserves the employer's right to levy LD. |
| 3 | **Contractual Requirements** | Comply with notice requirements strictly. Late notice can be a time-bar. |
| 4 | **Do NOT "Wait and See"** | Analyse delay impact contemporaneously. Prospective analysis is preferred over retrospective. |
| 5 | **Procedure for Granting EOT** | Contract Administrator should assess and grant EOT promptly. |
| 6 | **Effect of Delay** | Distinguish between employer risk events and contractor risk events. |
| 7 | **Incremental Review** | Review EOT entitlement incrementally as delay events occur. |
| 8–9 | **Float** | Float belongs to the project, not one party. See Section 2.3 for negative float. |
| 10 | **Concurrent Delay & EOT** | Contractor entitled to EOT for employer delay even if concurrent with contractor delay. |
| 11 | **Time-Distant Analysis** | Use recognised methods for retrospective analysis (see Part 4). |
| 12 | **EOT ≠ Compensation** | EOT entitlement does not automatically mean compensation. |
| 13 | **Early Completion** | Employer delay consuming terminal float may still entitle contractor to compensation. |
| 14 | **Concurrent Delay & Compensation** | Contractor may not recover prolongation costs during concurrent delay periods. |
| 15 | **Mitigation** | Both parties have mitigation obligations. |
| 16 | **Acceleration** | Directed → compensation. Voluntary → own cost. Constructive → may claim costs (notify first!). |
| 17 | **Global Claims** | Permissible only when impracticable to separate causes/effects. Courts are sceptical. |
| 18 | **Disruption** | Distinct from delay. Prove using measured mile, project-specific study, earned value, or industry studies. |
| 19 | **Variations** | Variations can cause both time and cost impact. Consider disruptive effect. |
| 20 | **Prolongation Costs** | Based on actual additional cost incurred due to extended time on site. |
| 21 | **Tender Allowances** | Actual cost, not tender rates, should be the basis for prolongation compensation. |
| 22 | **Period of Evaluation** | Assess compensation for the period the delay actually affected. |

---

## Part 4: Delay Analysis Methods

### Method Frameworks

Two recognised frameworks:
- **SCL Protocol** (UK) — identifies six delay analysis methodologies
- **AACEi Recommended Practice 29R-03** (US) — classifies methods using a 9-method matrix

Both are accepted in international arbitration.

### Overview — Seven Methods

| Method | When Used | Prospective/Retrospective | Complexity |
|--------|-----------|--------------------------|------------|
| **As-Planned vs As-Built** | Simple comparison | Retrospective | Low |
| **Impacted As-Planned** | Add delay events to baseline | Prospective | Medium |
| **Collapsed As-Built (But-For)** | Remove delay events from as-built | Retrospective | Medium-High |
| **Time Impact Analysis (TIA)** | Insert delay events at time they occurred | Both | High |
| **Windows Analysis** | Divide project into time windows | Both | High |
| **Retrospective Longest Path** | Trace longest path on as-built | Retrospective | Medium |

### As-Planned vs As-Built
- Compare the original programme to what actually happened
- **Pros:** Simple, easy to understand
- **Cons:** Doesn't show causation; doesn't account for logic changes
- **Best for:** Initial overview or simple disputes

### Impacted As-Planned
- Start with the baseline programme; add delay events as constraints
- **Pros:** Forward-looking; easy to model
- **Cons:** Assumes baseline was realistic; doesn't consider actual progress
- **Best for:** Early-stage EOT applications

### Collapsed As-Built (But-For)
- Start with the as-built programme; remove delay events
- **Pros:** Based on what actually happened
- **Cons:** Difficult to reconstruct; subjective removal of events
- **Best for:** Post-completion claims

### Time Impact Analysis (TIA) — Preferred Method
- Insert each delay event into the programme at the time it occurred
- Analyse the critical path impact of each event progressively
- **Pros:** Most rigorous; shows causation; accepted by tribunals; handles negative float correctly
- **Cons:** Resource-intensive; requires good records and updated programmes
- **Best for:** Complex projects, especially where negative float is present

### Windows Analysis
- Divide the project into time "windows" (e.g. monthly or by milestone)
- Analyse the critical path and delays within each window
- **Pros:** Systematic; handles concurrent delays well
- **Cons:** Window boundary selection is subjective; very resource-intensive
- **Best for:** Large projects with many delay events

### Retrospective Longest Path Analysis
- Identify the longest path on the as-built programme (the actual critical path)
- Walk back through the activities and identify what delayed each one
- **Pros:** Grounded in what actually happened; intuitive; useful when baseline is disputed
- **Cons:** May ignore parallel critical paths; can miss delays absorbed by float
- **Best for:** Disputes where the baseline programme is challenged

### Choosing a Method

**For prospective/ongoing analysis:**
- Time Impact Analysis — insert delay events as they occur
- Impacted As-Planned — for quick early-stage EOT applications

**For retrospective/post-completion analysis:**
- Windows Analysis — if many delay events across the project
- Collapsed As-Built — if isolating specific employer delay events
- Retrospective Longest Path — if as-built records are strong but baseline is disputed

---

## Part 5: Disruption Claims — How to Prove It

### The Walter Lilly Test (UK, 2012)

Four elements:
1. **Compensable event** — identify the contract clause
2. **Event caused disruption** — causal link (but-for test)
3. **Disruption caused loss** — quantify the financial impact
4. **Notice given** — comply with contractual notice requirements

### Causation Standard

Per *Costain Ltd v Charles Haswell & Partners Ltd* [2009] EWHC B25 (TCC): the contractor must prove not just that disruption occurred but that the **specific event caused identifiable productivity loss**. General assertions of "inefficiency" without linking specific events to specific losses will fail.

**Practical implication:** For each disruption claim, build a causation chain:
1. What was the event?
2. Which activities were affected?
3. What was the productivity benchmark?
4. What was the actual productivity?
5. What is the difference in cost?

### How to Quantify Disruption

| Method | Description | Persuasiveness |
|--------|-------------|----------------|
| **Measured Mile** | Compare productivity in disrupted vs undisrupted period on the same project | Highest |
| **Project-Specific Study** | Detailed analysis of the project's productivity data | High |
| **Earned Value Analysis** | Compare planned vs actual resource usage per unit of work | Medium-High |
| **Industry Studies** | Published productivity loss factors (Leonard, MCAA) | Lower |
| **System Dynamics** | Computer modelling of productivity impacts | Variable |

Measured Mile is the most accepted method. Industry studies are weakest because tribunals view them as too generic.

### Common Causes of Disruption

- Variations / change orders
- Late information or approvals
- Change in work sequencing
- Restricted site access
- Trade stacking (too many trades in same area)
- Acceleration instructions

---

## Part 6: Force Majeure & Frustration

### Force Majeure (Contract-Based)

- Defined in the contract — check the specific FM clause
- Consequences depend on contract terms (EOT? Termination? Cost sharing?)
- Common FM events: war, pandemic, natural disaster, government action

#### Hardship vs Force Majeure

**Hardship is NOT Force Majeure.** An event becoming more expensive or difficult does not qualify as FM. FM requires the event to make performance **impossible or legally impermissible**, not merely uneconomical.

#### COVID-19 Lessons

- Generic FM clauses without specific pandemic reference often failed to trigger
- Government-mandated shutdowns generally qualified as FM (or "change in law")
- Modern FM clauses now expressly list "pandemic", "epidemic", and "public health emergency"
- Notice and mitigation obligations were strictly enforced

### Frustration (Common Law — Last Resort)

- Contract is discharged — both parties walk away
- Only applies when performance is impossible, illegal, or radically different
- Very rarely successful — courts set a very high bar
- **NOT frustration:** cost increases, labour shortages, bad weather, design changes

---

## Part 7: Key Case Law Quick Reference

| Case | Jurisdiction | Key Principle |
|------|-------------|---------------|
| *Henry Boot v Malmaison* [1999] | UK | Concurrent delay — contractor gets EOT even if own delay is concurrent |
| *Walter Lilly v Mackay* [2012] | UK | Disruption: 4 elements + notice; global basis possible |
| *North Midland v Cyden Homes* [2018] EWCA Civ 1744 | UK | Parties can contract out of Malmaison — concurrent delay risk allocation is enforceable |
| *City Inn v Shepherd* [2010] CSIH 68 | Scotland | Apportionment approach — tribunal can split EOT between causes |
| *Costain v Charles Haswell* [2009] EWHC B25 (TCC) | UK | Disruption causation — must link specific events to specific productivity losses |
| *Cleveland Bridge* [2012] | UK | Reasoned assessment on balance of probabilities |
| *Van Oord v Allseas* [2015] | UK | Notice requirements matter |
| *Alliance Concrete v Sato Kogyo* [2014] | Singapore | Frustration — high bar for frustration |
| *Davis Contractors v Fareham* [1956] | UK | Frustration — 8-to-22-month overrun NOT frustration |
| *Evergreat v Presscrete* [2006] | Singapore | Employer must do all things necessary for completion |
| *TT International v Ho Lee* [2017] | Singapore | Employer must not prevent contractor from performing |
| *Zurich Insurance v B-Gold* [2008] | Singapore | Extrinsic evidence admissible for contract interpretation |
| *Lim Chin San v LW Infrastructure* [2011] | Singapore | Proper assessment by SO required; failure opens right to damages |
| *John Doyle v Laing* [2004] | UK | Global claims — permissible if impracticable to separate |
| *Wong Lai Ying v Chinachem* [1979] | Hong Kong | Unforeseeable landslip = frustration |

---

## Part 8: Key Definitions

| Term | Definition |
|------|-----------|
| **EOT** | Extension of Time — additional time to complete without LD |
| **LD** | Liquidated Damages — pre-agreed daily rate for late completion |
| **Critical Path** | Longest chain of dependent activities determining completion date |
| **Positive Float** | Time an activity can be delayed without affecting the critical path |
| **Zero Float** | Activity is on the critical path — any delay directly delays completion |
| **Negative Float** | Projected completion already exceeds contract completion date. Does NOT bar EOT claims. |
| **Terminal Float** | Buffer between contractor's planned completion and contract completion date |
| **Pacing Delay** | Deliberate slowing of non-critical work to match employer-caused critical path delay. Not contractor culpable delay. |
| **Excusable Delay** | A delay that entitles the contractor to EOT. May or may not be compensable. |
| **Compensable Delay** | A delay that entitles the contractor to both EOT and money. |
| **Inexcusable Delay** | A contractor risk delay — no EOT, no compensation. |
| **Logic Links** | Programme dependencies: FS (Finish-to-Start), SS (Start-to-Start), FF (Finish-to-Finish), SF (Start-to-Finish, rare). |
| **Approved Programme** | Programme formally accepted by the Employer/Engineer. Reference point for delay analysis. |
| **Working Programme** | Contractor's internal updated programme reflecting current progress and forecasts. |
| **Baseline Programme** | Original approved programme — reference point for delay analysis |
| **As-Built Programme** | Record of what actually happened |
| **Time-Bar** | Contractual deadline — miss it and you lose the claim |
| **Prolongation** | Extended site presence due to delay |
| **Disruption** | Reduced productivity (more resources per unit of output) |
| **Acceleration** | Measures to recover delay (additional resources, overtime, resequencing) |
| **Concurrent Delay** | Two or more delay events occurring simultaneously, at least one employer risk and one contractor risk |
| **Compensation Event** | NEC term for an event entitling contractor to time and/or money |
| **Measured Mile** | Comparing productivity in disrupted vs undisrupted periods |

---

*This document is based on publicly available sources including the SCL Delay and Disruption Protocol (2nd Ed, Feb 2017 + Rider 1, Feb 2022), AACEi RP 29R-03, and published case law. It is a study and reference aid only. It does not constitute legal advice. Users should verify all information against their specific contract terms and seek qualified legal counsel where required.*


path: references/disruption_claims.md
content: # Disruption Claims Strategy

Disruption claims seek compensation for **loss of productivity or inefficiency** caused by events that do not necessarily delay the overall completion date. They are often more difficult to prove than pure delay claims but can represent significant value.

---

## Key Characteristics

- Focus on **loss of productivity** rather than delay to completion
- Often arise from **cumulative effects** of multiple instructions, changes, or interference
- Require strong evidence linking disrupting events to reduced efficiency
- Usually quantified using **Measured Mile**, productivity studies, or actual cost comparison

---

## Strategic Approach — 7-Dimension Framework

### 1. Situation Assessment & Scope Control

Clearly define the claim as a **disruption/productivity claim**, not an EOT claim. Avoid mixing the two unless both are genuinely present and can be separated.

### 2. Argument Strategy

- In **common law** contexts: strong factual evidence and a credible Measured Mile are usually important
- In **civil law** or mixed settings: good faith and fairness may also support the overall impact argument, but factual evidence remains essential

### 3. Disclosure Control

Be cautious with early disclosure of internal productivity data or tender assumptions. Consider phased disclosure where appropriate.

### 4. Risk Assessment

A major risk is the argument that some disruption was **normal and priced in the tender**. Mitigate by demonstrating that the volume, nature, timing, or cumulative effect exceeded normal expectations.

---

## Recommended Primary Argument

**Factual Distinction** is usually the strongest approach:

1. Acknowledge that some level of instruction or change is normal under the contract
2. Distinguish **why** the actual events created materially different and more inefficient working conditions than could reasonably have been anticipated

---

## Common Law vs Civil Law Comparison

| Aspect | Common Law | Civil Law |
|--------|-----------|-----------|
| **Evidential standard** | Strong emphasis on proof of productivity loss | More reliance on good faith and fairness |
| **Measured Mile** | Highly regarded when properly applied | Less rigid requirement for a perfect comparison |
| **Baseline assumptions** | Greater scrutiny on productivity assumptions | Focus on whether changes exceeded reasonable expectations |
| **Cumulative impact** | Needs clear causal chain | May consider cumulative impact and equity |

**Strategic implication:** In common law jurisdictions, invest heavily in strong factual evidence and credible Measured Mile analysis. In civil law or international arbitration, balance factual evidence with fairness and overall impact arguments.

---

## Illustrative Scenarios

### Scenario A — Cumulative Instructions

A contractor experiences 47 instructions over 8 months. Productivity on finishing trades drops significantly. Using a Measured Mile from an unaffected period, the contractor demonstrates a 28% productivity loss. A tribunal would likely scrutinise the quality of the Measured Mile and the link between instructions and loss.

### Scenario B — Repeated Interference

The Employer repeatedly changes access arrangements and work sequences at short notice. The contractor argues that the cumulative effect made efficient working impossible. In a civil law or good faith context, the argument may focus on the Employer not creating conditions that undermine efficient performance.

---

## Arbitration Considerations for Disruption Claims

- Clearly separate disruption from any concurrent EOT claim
- Use clear visuals — productivity charts and comparison tables
- Justify why the level of disruption exceeded what was reasonably foreseeable at tender stage
- In international arbitration, explain which legal tradition or hybrid approach should apply based on the governing law clause

---

*This is a generic strategic guide. It does not constitute legal advice.*


path: references/expert_engagement.md
content: # Expert Engagement Tips

Experts — including delay analysts, quantum experts, and technical experts — can significantly strengthen complex claims, but they must be engaged strategically.

---

## When to Engage Experts

- Complex delay analysis is required (critical path or concurrent delay analysis)
- Quantum is large or difficult to calculate
- Technical issues are central to the dispute (design, workmanship, ground conditions)
- The other side has already engaged experts
- The matter is heading to adjudication, arbitration, or litigation

---

## Best Practices

1. **Engage experts early** — do not wait until the last minute
2. **Choose experts with relevant experience** in your jurisdiction and contract type
3. **Provide clear instructions** and all relevant documents
4. **Ensure independence and objectivity** — the expert's duty is to the tribunal, not the party
5. **Ask for clear methodology** and stated assumptions in the report
6. **Consider joint experts** — agreed by both parties — where beneficial
7. **Budget for expert costs** — they can be significant in arbitration

---

## Types of Expert

| Expert Type | Typical Scope | When Needed |
|-------------|---------------|-------------|
| **Delay Analyst** | Critical path analysis, concurrent delay, programme analysis | EOT and prolongation claims |
| **Quantum Expert** | Cost assessment, formula calculations, loss quantification | Large or complex quantum claims |
| **Technical Expert** | Design review, workmanship assessment, defects analysis | Technical disputes |
| **Programming Expert** | Programme review, baseline assessment, progress analysis | Complex programme disputes |

---

## Expert Reports — What Tribunals Expect

- Clear statement of qualifications and experience
- Independence declaration
- Stated methodology and assumptions
- Clear opinion on disputed issues
- Logical structure linking evidence to conclusions
- Awareness of limitations and alternative interpretations

---

## Common Mistakes in Expert Engagement

- Engaging too late (expert cannot properly review the records)
- Choosing an expert without relevant jurisdiction experience
- Providing incomplete or selective documentation
- Allowing the expert to become an advocate rather than independent analyst
- Not discussing methodology before the report is produced

---

*This is a generic reference guide. It does not constitute legal advice.*


path: references/legal_precedents.md
content: # Legal Precedents in Construction Claims

Legal precedents and case law can influence how construction claims are interpreted and decided. Their importance and application vary significantly between legal systems.

> **Important caution:** Specific legal precedents are highly jurisdiction-specific. Always seek advice from qualified legal counsel familiar with the governing law of the contract.

---

## Common Law vs Civil Law Approach

| Aspect | Common Law | Civil Law |
|--------|-----------|-----------|
| **Source of law** | Judicial precedents are usually an important source | Codified statutes and general principles are central |
| **Previous decisions** | Binding or highly persuasive | Persuasive but not applied in the same binding way |
| **Focus** | Wording of the contract, previous case interpretation | Wording of civil code, fairness, contractual intention |
| **Good faith** | Developing but not uniformly applied | Central principle in most civil law systems |

---

## Key Areas Where Precedents Commonly Influence Claims

- **Notice requirements and time bars** — what constitutes valid notice and whether strict time bars are enforceable
- **Prevention Principle** and related good faith concepts
- **Concurrent delay** — dominant cause, apportionment, and first-in-time arguments
- **Quantum methods** — acceptance of Eichleay, Hudson, Emden, actual cost, and total cost approaches
- **Global or total cost claims** — often treated cautiously if poorly substantiated
- **Mitigation duty** — extent to which a party must take reasonable steps to reduce loss

---

## The Prevention Principle — Practical Explanation

The Prevention Principle is generally understood as a doctrine that prevents a party from taking advantage of its own wrongdoing or breach to the detriment of the other party.

### In Common Law

Classic examples include situations where the Employer causes delay and then seeks to enforce the original contractual completion date or liquidated damages for the affected period. The principle often interacts with notice requirements and extension of time clauses.

### In Civil Law

Equivalent protections may arise through duties of good faith and fairness. The exact approach depends on the governing law and project-specific contract terms.

### Practical Implications for Claims

- If claiming an Extension of Time due to Employer-caused events, prevention or good faith arguments may support the primary contractual entitlement
- Such arguments may assist where the Employer's own conduct made strict compliance difficult
- They should **not** be used as a substitute for notice compliance where notice was reasonably possible
- Always verify the current status and relevance of any case or precedent relied upon

---

*This is a generic reference guide. It does not constitute legal advice. Users should verify the applicability of any legal principle to their specific jurisdiction and contract.*


path: references/notice_requirements_checklist.md
content: # Notice Requirements Checklist

Failure to comply with notice requirements is one of the most common reasons claims are rejected or reduced.

Use this checklist for **every potential claim event**.

---

## Checklist

- [ ] Identify the specific notice clause(s) in the Contract
- [ ] Note the required timeframe for giving notice (e.g. 7, 14, or 28 days)
- [ ] Determine when the event or awareness occurred
- [ ] Prepare and send the notice within the required timeframe
- [ ] Keep proof of delivery/receipt of the notice
- [ ] Ensure the notice contains all required information (description of event, anticipated effects)
- [ ] Follow up with detailed particulars within any further deadlines
- [ ] Record all notices in a central register with dates and references
- [ ] Monitor for any time bar provisions that could affect the claim
- [ ] Consider sending protective notices even if effects are not yet fully known

---

## Key Principles

### Protective Notices

When in doubt, issue a protective notice. It is far easier to withdraw a notice that proves unnecessary than to revive a claim after a time bar has passed.

### Notice Registers

Maintain a central notice register that tracks:
- Notice number and date
- Clause relied upon
- Event described
- Deadline for further particulars
- Status (submitted / pending / withdrawn)

### Common Mistakes

- Assuming verbal notification is sufficient
- Missing the "awareness" vs "occurrence" distinction
- Sending notice to the wrong party or address
- Failing to include the required contractual language
- Not following up within deadlines for further particulars

---

*This is a generic checklist. It does not constitute legal advice. Users should verify the specific notice requirements in their contract.*


path: references/quantum_worked_examples.md
content: # Quantum Calculation Worked Examples

Below are practical worked examples using different quantum methods. Where possible, base quantum on actual costs supported by records.

---

## Method Overview

| Method | Description | Best For | Acceptance |
|--------|-------------|----------|------------|
| **Actual Cost** | Claim based on real additional costs incurred | All claims | High in both Common Law and Civil Law |
| **Measured Mile** | Compare productivity in unaffected vs affected period | Disruption | High in both systems |
| **Eichleay Formula** | Head office overheads allocable to a contract during delay | Prolongation | More accepted in Common Law |
| **Hudson Formula** | Uses tendered overhead & profit percentage | Prolongation | Used in some Common Law countries |
| **Emden Formula** | Uses actual overhead percentage | Prolongation | Accepted in Common Law |
| **Total Cost** | Difference between actual cost and tender allowance | Last resort | Low — viewed with caution |

---

## Example 1: Eichleay Formula — Prolongation Overhead

**Given:**
- Total Company Billings during delay period: **$50,000,000**
- Contract Billings during delay period: **$8,000,000**
- Total Company Overhead during delay period: **$4,000,000**
- Original Contract Period: **24 months**
- Period of Delay: **4 months**

**Calculation:**

1. Contract billings ratio = $8,000,000 ÷ $50,000,000 = **0.16**
2. Overhead allocable to contract = 0.16 × $4,000,000 = **$640,000**
3. Monthly overhead rate = $640,000 ÷ 24 months = **$26,666.67 per month**
4. Overhead for delay period = $26,666.67 × 4 months = **$106,667**

**Claimed Amount: $106,667**

---

## Example 2: Hudson Formula — Prolongation Overhead

**Given:**
- Contract Sum: **$10,000,000**
- Tendered Head Office Overhead & Profit: **10%**
- Original Contract Period: **730 days** (24 months)
- Period of Delay: **120 days**

**Calculation:**

1. Daily overhead & profit rate = ($10,000,000 × 10%) ÷ 730 = **$1,369.86 per day**
2. Overhead & profit for delay = $1,369.86 × 120 days = **$164,383**

**Claimed Amount: $164,383**

---

## Example 3: Emden Formula — Prolongation Overhead

**Given:**
- Contract Value: **$12,000,000**
- Actual Head Office Overhead: **8%**
- Original Contract Period: **600 days**
- Period of Delay: **90 days**

**Calculation:**

1. Daily overhead rate = ($12,000,000 × 8%) ÷ 600 = **$1,600 per day**
2. Overhead for delay = $1,600 × 90 days = **$144,000**

**Claimed Amount: $144,000**

> **Note:** The Emden Formula is generally considered more accurate than Hudson because it uses actual overheads rather than tendered percentages.

---

## Example 4: Measured Mile — Piling Works (Disruption)

**Given:**
- Measured Mile (Unaffected Period): 800 piles installed using 4,000 man-hours → **0.2 piles per man-hour**
- Disrupted Period: 1,200 piles installed using 9,000 man-hours → **0.133 piles per man-hour**

**Calculation:**

1. Productivity Loss: 0.2 − 0.133 = **0.067 piles per man-hour** (33.5% loss)
2. Hours at Measured Mile rate: 1,200 ÷ 0.2 = **6,000 man-hours**
3. Additional man-hours claimed: 9,000 − 6,000 = **3,000 man-hours**

**Claimed Amount:** 3,000 man-hours × applicable labour rate

---

## Example 5: Measured Mile — Formwork Installation (Disruption)

**Given:**
- Measured Mile (Normal Period): 2,500 m² installed using 5,000 man-hours → **0.5 m² per man-hour**
- Disrupted Period: 3,000 m² installed using 8,000 man-hours → **0.375 m² per man-hour**

**Calculation:**

1. Productivity Loss: 0.5 − 0.375 = **0.125 m² per man-hour** (25% loss)
2. Hours at Measured Mile rate: 3,000 ÷ 0.5 = **6,000 man-hours**
3. Additional man-hours: 8,000 − 6,000 = **2,000 man-hours**

**Claimed Amount:** 2,000 man-hours × applicable labour rate

---

## Example 6: Actual Cost Method — Preliminaries Prolongation

Project extended by **5 months** due to Authority-caused events.

| Item | Monthly Cost | Duration | Amount |
|------|-------------|----------|--------|
| Site Supervision & Management | $28,000 | 5 months | $140,000 |
| Site Accommodation & Facilities | $12,000 | 5 months | $60,000 |
| Utilities & Site Services | $4,500 | 5 months | $22,500 |
| Additional Security | $3,200 | 5 months | $16,000 |
| **TOTAL** | | | **$238,500** |

**Claimed Amount: $238,500**

---

## Example 7: Simple Productivity Loss Calculation

**Given:**
- Tender productivity for concrete works: **4 m³ per man-day**
- Actual average productivity during disruption: **2.8 m³ per man-day**
- Total volume placed during disrupted period: **1,400 m³**

**Calculation:**

1. Man-days at tender rate: 1,400 ÷ 4 = **350 man-days**
2. Actual man-days used: 1,400 ÷ 2.8 ≈ **500 man-days**
3. Additional man-days claimed: 500 − 350 = **150 man-days**

**Claimed Amount:** 150 man-days × applicable labour rate

---

## Example 8: Total Cost Method — Use with Strong Caution

**Given:**
- Tendered cost for the affected scope: **$2,500,000**
- Actual cost incurred: **$3,450,000**

**Claimed Amount:** $3,450,000 − $2,500,000 = **$950,000**

> **Important Warning:** The Total Cost Method is generally viewed with suspicion by tribunals and courts because it assumes that *all* cost overruns are the responsibility of the other party. It should only be used as a **last resort** when no better method is available, and even then, it requires very strong justification and supporting evidence.

---

## Recommendation by Claim Type

| Claim Type | Preferred Method | Fallback |
|-----------|-----------------|----------|
| **Variation** | Actual Cost | Rates-based valuation |
| **Disruption** | Measured Mile | Actual Cost comparison |
| **Prolongation** | Actual Cost | Eichleay or Emden |
| **Combined** | Keep EOT and Disruption quantum separate and clearly labelled | — |

---

## Civil Law vs Common Law Notes

- **Common Law:** More familiar with formula-based methods (Eichleay, Hudson, Emden); more developed case law
- **Civil Law:** Generally prefer claims based on **actual proven costs**; may require stronger justification for formulas
- **Best Practice:** Wherever possible, support quantum with **actual records**; use formulas only as secondary/alternative methods

---

*This is a generic reference guide. It does not constitute legal advice.*


path: references/quick_reference_card.md
content: # Quick Reference Card

**Construction Claim Strategy v1.1 — One-Page Reference**

---

## Argument Strength Ranking (Always start from the top)

| Rank | Argument Type | Strength | When to Use | Recommendation |
|------|---|---|---|---|
| 1 | Textual Interpretation | **Strongest** | Wording supports your position | Lead with this |
| 2 | Factual Distinction | **Strong** | Facts are materially different | Strong alternative |
| 3 | Concede-then-Distinguish | Moderate-Strong | Clause appears unfavourable but facts are exceptional | Use carefully |
| 4 | Implied Terms / Prevention | **Weakest** | No stronger argument available | Last resort only |

## Disclosure Control Levels

| Level | Use For | Recommendation |
|---|---|---|
| **State Precisely** | Clause references, formal letters, key facts, legal reasoning | Preferred for strong arguments |
| **Keep General** | Operational context, high-level impact | Use for moderate/weak arguments |
| **Defer** | Detailed quantification & analysis | Almost always defer full details |

## Response Architecture Patterns

- **Standard Query Response** — Acknowledge → Address points → Reserve rights
- **Risk Allocation Rebuttal** — Concede normal position → Distinguish current facts → Conclude
- **Chronology-Based Response** — Timeline of events → Current status → Next steps
- **Cost / Quantum Claim Response** — Contractual basis → Heads of claim → Status → Reserve
- **Always close** with a Reservation of Rights paragraph

## Scope Control Rules (Critical)

1. Respond **only** to what was asked.
2. Do **not** volunteer new claims or unrequested information.
3. Preserve future rights using "reserves its position".
4. Keep operational details general until necessary.

## Common Anti-Patterns to Avoid

- ❌ Citing the wrong or weakest clause first
- ❌ Leading with defensive language ("the clause does not apply")
- ❌ Volunteering extra information
- ❌ Quantifying costs or delay too early
- ❌ Using implied terms when stronger arguments exist

---

## Practical Tips

- Always **start** by checking whether Textual Interpretation is available.
- Only move down the ranking when stronger options are weak or unavailable.
- **Combine arguments**: primary + fallback in the same response.
- Match disclosure level to argument strength: stronger = more precise.
- **Run the strategy wizard even for simple replies** — prevents mistakes.
- Apply Scope Control strictly — one of the biggest value-adds.

---

**Remember: Plan → Strategise → Draft**

*This is a workflow and analysis aid only. It does not constitute legal advice.*


path: references/record_keeping_checklist.md
content: # Record Keeping Checklist

Good record keeping is one of the most critical success factors in construction claims.

Use this checklist throughout the project and when preparing claims.

---

**Project:** _______________________________ **Date:** _______________

## A. Contractual Notices & Formal Correspondence

- [ ] All contractual notices submitted with proof of delivery/receipt
- [ ] Notice dates recorded against event dates
- [ ] All formal letters and emails organised by date
- [ ] Meeting minutes, especially those recording issues or agreements

## B. Instructions, Variations & Changes

- [ ] All instructions from the Authority/Engineer
- [ ] Variation orders and change directives
- [ ] Requests for Information (RFIs) and responses
- [ ] Revised drawings and specifications

## C. Programme & Progress Records

- [ ] Baseline programme
- [ ] All programme updates and revisions
- [ ] Weekly / monthly progress reports
- [ ] As-built records and progress photographs

## D. Daily / Site Records

- [ ] Site diaries and daily reports
- [ ] Labour allocation and deployment records
- [ ] Plant and equipment usage logs
- [ ] Material delivery and usage records
- [ ] Dated photographs and videos of site conditions

## E. Cost & Financial Records

- [ ] Invoices, payment certificates, and supporting documents
- [ ] Timesheets and payroll records
- [ ] Subcontractor and supplier claims
- [ ] Additional cost records, including preliminaries, plant, and materials

## F. General Record Keeping Standards

- [ ] Records are factual, objective, and made contemporaneously
- [ ] Records are properly filed and easy to retrieve
- [ ] Electronic backups are maintained and secure
- [ ] Key records are cross-referenced to specific events or claim items

**Reviewed by:** ___________________________ **Date:** _______________

---

*This is a generic checklist. It does not constitute legal advice.*


path: references/response_template.md
content: # Response Letter Template

*Use this template after completing a strategy report to draft the formal response.*

---

## Standard Response Structure

```
Subject: Response to [Authority/Employer] Letter dated [Date] – [Subject]

Dear [Name / Sir/Madam],

1. INTRODUCTION / ACKNOWLEDGEMENT
We refer to your letter dated [Date] regarding [brief subject].

2. SCOPE OF RESPONSE
This response addresses only the matters raised in your letter.
We reserve our position on all other matters.

3. PRIMARY POSITION
[Insert your strongest argument here – usually Textual Interpretation
or Factual Distinction]

4. ALTERNATIVE / FALLBACK POSITION (if needed)
Without prejudice to the above, even if [alternative interpretation],
the facts of this case are materially different because...

5. DISCLOSURE
We provide the following information:
- [Precise information – clause references, key facts, dates]
- [General information – high-level context only]

Further detailed quantification and analysis will be provided in due course.

6. CONCLUSION & RESERVATION OF RIGHTS
For the reasons set out above, the Contractor maintains its position
that it is entitled to [relief].

We reserve all our rights and remedies under the Contract and at law.

Yours faithfully,

[Name]
[Position]
```

---

## How to Map Strategy Report → Response Letter

| Strategy Report Section | Letter Section | Notes |
|---|---|---|
| Situation Assessment | Introduction | Keep brief |
| Scope Control | Scope of Response | Critical — prevents scope creep |
| Primary Argument | Primary Position | Be clear and structured |
| Fallback Argument | Alternative Position | Use "Without prejudice to the above" |
| Disclosure Control | Disclosure section | Follow precisely / generally / defer |
| Response Architecture | Overall structure | Choose the right pattern |
| Risk Assessment | Internal use only | Helps prepare for counter-arguments |

---

## Closing Patterns

### Standard Reservation of Rights
> Nothing in this response shall be construed as a waiver of, or prejudice to, any of the Contractor's rights, remedies, claims or entitlements, whether under the Contract, at law or otherwise, all of which are expressly reserved.

### Cooperative Closing
> The Contractor remains committed to working cooperatively with the [Authority/Employer] to resolve this matter.

### Deferral of Full Particulars
> Further particulars, supporting records, and detailed quantification will be provided in the [Notified Claim Report / formal submission] once the full effects of the event become ascertainable.

---

*This is a workflow and analysis aid only. It does not constitute legal advice.*


path: references/risk_assessment_framework.md
content: # Risk Assessment Framework

Use this framework during the Risk Assessment dimension to evaluate your position honestly and systematically.

---

## Risk Categories

| Category | Key Questions to Ask | Typical Mitigation |
|----------|---------------------|-------------------|
| **Notice Timing** | Was notice given on time? When did awareness occur? | Explain awareness date; use Factual Distinction if appropriate |
| **Causation** | Can I clearly link event to delay/productivity loss? | Gather best evidence; consider expert support |
| **Quantum Strength** | Are records complete and reliable? | Defer detailed quantum if records are weak |
| **Contract Interpretation** | How might the other side interpret key clauses? | Prepare strong textual and factual arguments |
| **Evidential Gaps** | What key evidence is missing? | Identify gaps early and plan how to address them |
| **Relationship Risk** | Will this damage the commercial relationship? | Maintain professional tone throughout |
| **Time Bar / Limitation** | Are there contractual or legal time limits? | Check early and address proactively |

---

## Practical Risk Assessment Questions

Ask yourself these questions during the Risk Assessment stage:

1. What is the **single weakest point** in my position?
2. What is the **most likely counter-argument** the other side will raise?
3. If I were advising the other side, how would I attack this claim?
4. What **evidence am I still missing**?
5. What is the **worst-case outcome** if this goes to dispute?

---

## Risk Rating Template

| Risk Category | Description | Likelihood | Impact | Mitigation Strategy |
|---------------|-------------|-----------|--------|-------------------|
| Notice timing | _e.g. Notice submitted late_ | High / Medium / Low | High / Medium / Low | _e.g. Explain when awareness occurred_ |
| Causation | _e.g. Difficult to link event to delay_ | | | |
| Quantum | _e.g. Records are incomplete_ | | | |
| Counter-argument | _e.g. Other side claims events were normal_ | | | |
| Relationship | _e.g. Response seen as too aggressive_ | | | |

---

## Best Practice

Be **honest** during Risk Assessment. The goal is not to make your position look perfect, but to understand it realistically so you can:
- Strengthen weak areas before submission
- Prepare for pushback
- Decide on appropriate disclosure levels
- Choose the right argument strategy

---

*This is a generic framework. It does not constitute legal advice.*


path: references/seven_dimensions_guide.md
content: # 7-Dimension Framework — Detailed Guide

*Complete explanation of each dimension with examples and practical tips.*

---

## Overview

The 7-Dimension Framework forces you to think strategically **before** drafting. The dimensions work in sequence:

- **Dimensions 1–3** → Define the battlefield (what, scope, direction)
- **Dimensions 4–5** → Decide *how* to argue and *how much* to reveal
- **Dimension 6** → Choose the most effective way to present it
- **Dimension 7** → Stress-test your position before sending

---

## Dimension 1: Situation Assessment

**What it is:** Understanding exactly what you are responding to and why.

**Why it matters:** Many responses go wrong because people don't fully clarify the trigger.

**Key questions:**
- What document or event triggered this response?
- What is the other party actually asking for or claiming?
- What is the background and context?

**Good vs poor assessment:**

| Scenario | Good | Poor |
|---|---|---|
| Authority sends letter requesting info | "Responding to the Authority's letter dated [X] which requests clarification on the basis of our claim for additional time arising from Instruction No. Y." | "We need to reply to the Authority about the claim." |
| Multiple letters exchanged | "This is the third exchange. The current letter raises three specific points we have not previously addressed." | "We have to respond again about the same issue." |

**Practical tip:** Be specific. Vague understanding at this stage leads to unfocused responses.

---

## Dimension 2: Scope Control

**What it is:** Deciding what you **must** address and what you should **avoid** volunteering.

**Why it matters:** One of the most common mistakes is volunteering information that was not requested. This can create new problems or weaken your position.

**Key questions:**
- What specific points must I reply to?
- What should I deliberately **not** mention?
- How can I preserve my rights on other matters?

**Good vs poor scope control:**

| Situation | Good | Poor |
|---|---|---|
| Authority asks about one instruction | Reply only addresses that instruction | Response also discusses two other potential claims |
| Authority questions notice timing | Clearly state awareness dates | Team explains entire project history and unrelated delays |
| Multiple topics in one letter | Number the response per points raised | Everything mixed together |

**Best practice phrase:**
> "This response is limited to the matters raised in your letter dated [Date]. We expressly reserve our position on all other issues."

**Practical tip:** Always define your "must avoid" items clearly. This is one of the highest-value parts of the framework.

---

## Dimension 3: Direction Decision

**What it is:** Choosing your **primary** argument, **fallback** position, and what to **avoid**.

**Why it matters:** Without clear direction, responses become confused or contradictory.

**Key questions:**
- What is my main argument?
- What is my backup if the primary is challenged?
- Which arguments or clauses should I avoid?

**Practical tip:** Always decide primary first, then identify a realistic fallback. This gives strength and flexibility.

---

## Dimension 4: Argument Strategy

**What it is:** Selecting the **type** of argument based on the strength ranking.

**The ranking:**
1. Textual Interpretation (Strongest)
2. Factual Distinction (Strong)
3. Concede-then-Distinguish (Moderate-Strong)
4. Implied Terms / Prevention Principle (Weakest)

**Why it matters:** Using a weak argument when a stronger one is available makes your position less credible.

**Deeper examples:**

| Argument Type | Situation | How to phrase it |
|---|---|---|
| Textual Interpretation | Clause clearly states entitlement when Authority issues an instruction with certain effects | "The clause states that the Contractor shall be entitled when the Authority issues an instruction which [effect]. The instruction issued had exactly that effect." |
| Factual Distinction | Clause requires notice within X days of becoming aware. Information was not available earlier. | "While the clause requires notice within X days of awareness, the full effect could not reasonably have been known until [later point] because [reason]." |
| Concede-then-Distinguish | Normal risk allocation places ground conditions risk on Contractor, but Authority provided incorrect information. | "We acknowledge that ground conditions risk would normally rest with the Contractor. However, the Authority provided specific information which proved materially incorrect, fundamentally changing the nature of the risk." |
| Implied Terms | Authority's delay in providing information prevented mitigation. | "It must be implied that the Authority would not hinder or prevent the Contractor from performing its obligations or mitigating its losses." |

**Practical tip:** Always try Textual Interpretation first. It is the cleanest and strongest.

---

## Dimension 5: Disclosure Control

**What it is:** Deciding **how much** information to reveal at this stage.

**The three levels:**
- **State Precisely** — Clause references, formal correspondence, key facts, legal reasoning
- **Keep General** — Operational context and high-level details
- **Defer** — Detailed quantification, delay analysis, cost breakdowns

**Deeper guidance:**

| Situation | Recommended Level | Why |
|---|---|---|
| Very strong textual argument | State Precisely | On solid ground — be clear and confident |
| Using Concede-then-Distinguish | Keep General on the distinction | Partial concession — don't over-explain |
| Still compiling records | Defer quantification | Avoid giving incomplete numbers |
| Other side is aggressive | Lean toward Keep General | Reduces material they can attack |
| Want to show cooperation | Mix of Precise + General | Builds credibility without over-disclosing |

**Golden rule:** Stronger argument → more precise disclosure. Weaker argument → more general.

**Practical tip:** Match disclosure level to argument strength.

---

## Dimension 6: Response Architecture

**What it is:** Choosing the overall **structure** of your reply.

**Common patterns:**

| Situation | Architecture | Why |
|---|---|---|
| Authority claims event falls under normal risk allocation | Risk Allocation Rebuttal | Directly addresses and distinguishes the risk argument |
| Complex sequence of events over months | Chronology-Based Response | Easier for the reader to follow |
| Responding to cost/variation questions | Cost / Quantum Claim Response | Structured around contractual basis and heads of claim |
| Simple request for clarification | Standard Query Response | Efficient and proportionate |

**Practical tip:** Risk Allocation Rebuttal is often powerful when the other side is pushing risk onto you.

---

## Dimension 7: Risk Assessment

**What it is:** Honestly identifying weaknesses, counter-arguments, and timing risks.

**Why it matters:** Ignoring risks doesn't make them disappear. Identifying them early allows better preparation.

**Practical examples:**

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Authority argues instruction was normal | High | High | Lead with Textual Interpretation + prepare Factual Distinction fallback |
| Notice was late | Medium | High | Use Factual Distinction to explain when awareness occurred |
| Incomplete records | High | Medium | Defer detailed quantification; commit to provide later |
| Response may damage relationship | Medium | Medium | Professional tone; "without prejudice" language |

**Good practice:** Always ask: "What is the weakest part of our position, and how might the other side attack it?"

**Practical tip:** Be honest here. The goal is not to look perfect, but to understand your position realistically.

---

## Summary

| Dimension | Main Purpose | Highest Value When... |
|---|---|---|
| 1. Situation Assessment | Clarity on what you're responding to | The trigger is complex |
| 2. Scope Control | Protect your position | Risk of volunteering too much |
| 3. Direction Decision | Clear strategic focus | Multiple possible arguments exist |
| 4. Argument Strategy | Use the strongest argument | You have a choice of arguments |
| 5. Disclosure Control | Control what you reveal | Matter is sensitive or high-value |
| 6. Response Architecture | Make the response persuasive | Reply needs to be structured |
| 7. Risk Assessment | Prepare for pushback | The other side is aggressive |

---

*This is a workflow and analysis aid only. It does not constitute legal advice.*


path: references/strategy_patterns.md
content: # Strategy Patterns — Quick Reference

## Argument Types (Ranked by Strength)

For construction contracts (all forms):

| Rank | Type | Strength | When to use |
|------|------|----------|-------------|
| 1 | Textual Interpretation | Strongest | Always start here. Win on the text and you need nothing else. |
| 2 | Factual Distinction | Strong | Text is broad but facts are extraordinary. Pairs with Rank 1. |
| 3 | Concede-then-Distinguish | Moderate-Strong | Risk allocation rebuttals. Concede ordinary, distinguish this case. |
| 4 | Implied Terms / Prevention Principle | Weakest | Last resort. Courts reluctant to imply terms over express clauses. |

**Rule:** Build from the clause wording first. If textual interpretation wins, stop. Don't reach for implied terms when the text supports you.

## Disclosure Control Levels

| Level | Use for | Examples |
|-------|---------|----------|
| **State Precisely** | Documented facts, letter refs, clause numbers | "Disposal facility closed [date] (ref. Contractor's letter [XXX])" |
| **Keep General** | Zones, quantities, operational details | "multiple designated zones" (not Zone A, Zone B) |
| **Defer** | Delay analysis, cost breakdown, programme | "will be provided in the Notified Claim Report" |

**Rule:** Be specific on legal arguments, general on operational facts, defer quantification.

## Response Architecture Patterns

### 1. Standard Authority Query Response
1. Acknowledge the Authority's position
2. Pivot to Contractor's primary contractual reliance
3. State primary argument (textual interpretation)
4. Reserve fallback clause(s) without elaborating
5. Close cooperatively

### 2. Risk Allocation Rebuttal (Concede-then-Distinguish)
1. Concede the ordinary application of the risk clause
2. Distinguish the extraordinary facts of THIS case
3. Provide factual support (before/after)
4. State legal conclusion (clause covers X, this is Y)
5. Show mitigation evidence (good faith)
6. Close cooperatively

### 3. Chronology / Details Response
1. State known facts with exact dates and references
2. Flag items still being compiled
3. Commit to supplementing in the Claim Report
4. Reserve right to provide further details

### 4. Cost Claim Response (Pre-Quantification)
1. Identify contractual basis for cost recovery (e.g., Cl. 63.1)
2. List heads of claim without quantifying
3. State disruption is ongoing / costs being assessed
4. Commit to detailed breakdown in the Claim Report
5. Reserve right to supplement

### 5. Reservation of Rights Closing
- Interim / without prejudice basis
- Reserve all rights, remedies, claims, entitlements
- Under the Contract, at law, or otherwise
- **Always use this. Every substantive response.**

## Scope Control Rules

| Rule | Description | Anti-pattern |
|------|-------------|-------------|
| Limit to letter | Reply only to what was asked | Volunteering a mitigation proposal narrative when the Employer only asked about the initial notice |
| Preserve future claims | "reserves its position" + "without prejudice" | Making absolute statements that limit future claims |
| Keep details general | Don't name zones/quantities early | Naming "Zone A, Zone B" when boundaries might shift |

## Risk Assessment Checklist

### Counter-Arguments
- What will the Authority argue?
- Which clauses might they cite?
- Any provisions that explicitly allocate this risk to us?
- Can they argue we failed to mitigate?

### Weak Points
- Notice timing vulnerable?
- Gaps in contemporaneous records?
- Inconsistencies in prior correspondence?
- Relying on verbal communications without written record?

### Timing Risks
- Response deadline?
- Disruption still ongoing?
- Parallel claims that interact?
- Could delay in responding trigger time-bar?

### Disclosure Risks
- Volunteering anything not asked about?
- Any statement usable against us later?
- Prematurely quantifying?
- Naming specifics we might need to change?

## Common Anti-Patterns

| ❌ Don't | ✅ Do instead |
|----------|--------------|
| Cite wrong clause (e.g. EOT clause for other contractors' acts when the delay is caused by the Employer) | Verify clause text against actual contract |
| Lead with "the clause doesn't apply" | Concede ordinary application, then distinguish |
| Volunteer topics not yet raised | Limit scope to the letter being replied to |
| Name specific zones/quantities early | Keep general: "multiple designated zones" |
| Reach for implied terms first | Start with textual interpretation |
| Hedge documented dates | Use exact dates for formal letters |
| Quantify costs before records are complete | List heads of claim, defer numbers |


path: references/training_guide.md
content: # Training Guide

**Construction Claim Strategy — Workshop Reference (v1.1)**

---

## Workshop Agenda

1. Why Strategic Planning Matters
2. The 7-Dimension Framework
3. Argument Strength Ranking — Deep Dive
4. Disclosure Control — Practical Guidance
5. Choosing the Right Response Structure
6. Using the Interactive Wizard Effectively
7. Turning Strategy into a Formal Response
8. Common Mistakes & How to Avoid Them
9. Best Practices & Pro Tips
10. Key Takeaways

---

## 1. Why Strategic Planning Matters

| Problem | Consequence |
|---|---|
| Jumping straight to clause selection | Arguments lack coherence and direction |
| No scope control | Volunteering information that creates new issues |
| Wrong argument type chosen | Position looks weak even when merits are strong |
| Over-disclosing early | Giving the other side material to attack |
| No risk assessment | Caught off-guard by counter-arguments |

**Key message:** A few minutes of strategic planning saves hours of rework and significantly improves the quality of the response.

---

## 2. The 7-Dimension Framework

| Dimension | Focus Area |
|---|---|
| 1. Situation Assessment | What exactly are we responding to? |
| 2. Scope Control | What to address, what to avoid |
| 3. Direction Decision | Primary + fallback arguments |
| 4. Argument Strategy | Which argument type to use |
| 5. Disclosure Control | Precise / General / Defer |
| 6. Response Architecture | Which structure pattern to use |
| 7. Risk Assessment | Counter-arguments and weak points |

---

## 3. Using the Wizard Effectively

### 5 Practical Tips

1. **Be specific in Dimension 1** — Name the exact letter/instruction you're responding to.
2. **Write down what you will NOT say** in Dimension 2 — scope control is about restraint.
3. **Always try Textual Interpretation first** in Dimension 4 — only move down the ranking if needed.
4. **Use the Review step** — this is where most improvements happen.
5. **Save the strategy** for reuse if the matter is ongoing.

---

## 4. Turning Strategy into a Formal Response

### Step-by-Step Flow

```
Strategy Report → Response Letter Template → Draft → Review → Final
```

| Strategy Report Section | Maps to Letter Section |
|---|---|
| Situation Assessment | Introduction / Acknowledgement |
| Scope Control | Scope of Response |
| Primary Argument | Primary Position |
| Fallback Argument | Alternative Position |
| Disclosure Control | What to include / what to defer |
| Risk Assessment | Internal preparation only |

---

## 5. Common Mistakes vs Fixes

| Mistake | Fix |
|---|---|
| Citing the weakest clause first | Start with the strongest textual argument |
| Saying "the clause does not apply" | Concede the ordinary case, then distinguish |
| Answering questions that weren't asked | Strictly follow scope control |
| Giving detailed costs before records are ready | Defer quantification to formal claim report |
| Using implied terms when express text supports you | Always check textual interpretation first |
| Same structure for every reply | Choose the right response architecture pattern |

---

## 6. Best Practices Summary

1. **Plan before drafting** — always run through the 7 dimensions.
2. **Lead with your strongest argument** — Textual Interpretation whenever possible.
3. **Combine primary + fallback** — shows strength while preserving alternatives.
4. **Match disclosure to argument strength** — stronger = more precise.
5. **Apply scope control strictly** — respond only to what was asked.
6. **Revisit the strategy** if new information appears before sending.

---

## 7. Key Takeaways

- Strategic planning is not optional — it's what separates strong claims from weak ones.
- The argument ranking exists because not all arguments carry the same weight.
- Disclosure control prevents you from giving the other side ammunition.
- Scope control prevents you from creating new problems.
- A structured response architecture makes your position more persuasive.

**Remember: Plan → Strategise → Draft**

---

## This Skill vs Traditional Approach

| Aspect | Traditional Approach | This Skill |
|---|---|---|
| Starting point | Drafting or selecting clauses | 7-dimension strategic analysis |
| Argument selection | First argument that comes to mind | Ranked by strength |
| Scope management | Often volunteers extra info | Explicit scope control step |
| Disclosure | Too much or too little | Clear disclosure levels |
| Response structure | Standard letter format | Consciously chosen architecture |
| Risk management | Considered late or not at all | Dedicated risk assessment |
| Consistency | Depends on individual experience | Repeatable framework |

**Biggest advantages appear on medium to high-value claims**, responses that need to preserve future rights, or when dealing with difficult counterparties.

---

*This is a workflow and analysis aid only. It does not constitute legal advice.*


path: references/worked_examples.md
content: # Worked Examples

*Fully generic scenarios demonstrating the 7-Dimension Framework in practice.*

---

## Example 1: Variation / Instruction Claim

### Scenario
The Authority issued an instruction that required changes to the works. The Contractor claims additional time and cost. The Authority has questioned the entitlement and requested further information.

### Strategy Worksheet

| Dimension | Decision |
|---|---|
| **Situation** | Responding to the Authority's letter requesting further information on an existing claim |
| **Scope** | Only address points in the latest letter; avoid new claims |
| **Direction** | Primary: Textual Interpretation. Fallback: Factual Distinction |
| **Argument** | Textual Interpretation (Strongest) — clause wording directly addresses instructions |
| **Disclosure** | Precise: clause refs + instruction date. General: impact on progress. Defer: quantification |
| **Architecture** | Risk Allocation Rebuttal |
| **Risk** | Authority may argue instruction was normal variation; notice timing may be questioned |

### Sample Response

**Subject:** Response to Letter dated [Date] – Request for Further Information Regarding Claim

Dear [Name],

**1. Introduction**
We refer to your letter dated [Date] in which you requested further information in relation to our claim for additional time and cost arising from the instruction issued by the Authority on [Date].

**2. Scope of Response**
This response addresses only the matters expressly raised in your letter dated [Date]. We do not address, and expressly reserve our position in respect of, any other matters.

**3. Primary Position – Textual Interpretation**
The Contract provides that the Contractor shall be entitled to additional time and cost where the Authority issues an instruction which has [describe the relevant effect as per the clause wording].

The instruction dated [Date] required the Contractor to [neutral description of the change required]. This instruction had the effect contemplated under the clause. Accordingly, the Contractor is entitled to additional time and cost pursuant to the clear wording of the Contract.

**4. Alternative Position – Factual Distinction**
Without prejudice to the Primary Position above, even if a more restrictive interpretation of the clause were applied, the facts of this case are materially different from those ordinarily contemplated by the Contract. The nature, scope, and consequences of the instruction were not of the type normally encountered in the administration of the Contract. On this alternative basis also, the Contractor maintains its entitlement to additional time and cost.

**5. Information Provided**
In response to the specific requests in your letter, we confirm the following:
- The relevant clause reference is [Clause reference].
- The instruction was issued on [Date] and received by the Contractor on [Date].
- The instruction required changes to [high-level description].

We are continuing to review our records in relation to the impact of the instruction. A more detailed analysis will be provided in due course.

**6. Next Steps**
We propose to provide a further submission containing our detailed assessment of the impact on the programme and associated costs by [proposed date or "within the next [X] weeks"], subject to the completion of our ongoing review.

**7. Reservation of Rights**
The Contractor maintains its position that it is entitled to additional time and cost as a result of the instruction. Nothing in this letter should be construed as a waiver of any rights or entitlements under the Contract or at law. We expressly reserve all such rights and remedies.

Yours faithfully,
[Name]
[Position]

---

## Example 2: Prolongation / Extension of Time Claim

### Scenario
The Contractor submitted a claim for an Extension of Time due to events that delayed the works. The Authority has rejected parts of the claim and requested further information on notice compliance and causation.

### Strategy Worksheet

| Dimension | Decision |
|---|---|
| **Situation** | Responding to partial rejection + request for further information on EOT claim |
| **Scope** | Address notice timing and causation only; avoid cost claims (time only) |
| **Direction** | Primary: Textual Interpretation (notice provisions) + Factual Distinction (awareness). Fallback: Concede-then-Distinguish on notice |
| **Argument** | Combination of Textual + Factual Distinction |
| **Disclosure** | Precise: event dates, notice dates, clause refs. General: delay impact. Defer: critical path analysis |
| **Architecture** | Risk Allocation Rebuttal + Chronology |
| **Risk** | Notice timing challenged; causation questioned; programme data requested early |

### Sample Response

**Subject:** Response to Letter dated [Date] – Extension of Time Claim

Dear [Name],

**1. Introduction**
We refer to your letter dated [Date] in which you requested further information and raised concerns regarding our Extension of Time claim.

**2. Scope of Response**
This response addresses the specific points raised in your letter concerning notice compliance and causation. We reserve our position on all other matters, including costs associated with the delay.

**3. Primary Position**
The Contract requires notice of a delaying event within a specified period after the Contractor became aware of the delay.

The events occurred on [dates], and the Contractor became aware of their delaying effect on [later date] because [brief neutral explanation]. Notice was submitted on [date], within the required period from the date of awareness.

The events directly impacted the critical path, as demonstrated in our previous submissions.

**4. Alternative Position**
Without prejudice to the above, even if the notice period is calculated from the date of the event itself, the circumstances were such that the full delaying effect could not reasonably have been known at that time. The Contractor acted as soon as it became aware of the impact.

**5. Information Provided**
We provide the following:
- Dates of the delaying events.
- Dates on which notices were submitted.
- High-level explanation of how the events affected progress.

A detailed updated programme analysis showing the impact on the critical path will be submitted within [X] weeks.

**6. Reservation of Rights**
The Contractor maintains its entitlement to an Extension of Time. We reserve all rights and remedies under the Contract and at law.

Yours faithfully,
[Name]
[Position]

---

## Example 3: Disruption / Loss of Productivity Claim

### Scenario
The Contractor claims loss of productivity due to multiple, cumulative instructions and repeated interference over several months. The Authority has rejected the claim and requested further information.

### Strategy Worksheet

| Dimension | Decision |
|---|---|
| **Situation** | Responding to rejection + request for info on disruption claim |
| **Scope** | Disruption only — keep separate from any EOT claim; avoid cost breakdown |
| **Direction** | Primary: Factual Distinction (cumulative effect). Fallback: Concede-then-Distinguish |
| **Argument** | Factual Distinction (Strong) — volume and nature of instructions created abnormal conditions |
| **Disclosure** | Precise: number and dates of instructions. General: productivity impact. Defer: man-hour analysis |
| **Architecture** | Risk Allocation Rebuttal (normal vs abnormal conditions) |
| **Risk** | Authority argues some disruption is normal risk; causation link is difficult; confused with EOT |

### Sample Response

**Subject:** Response to Letter dated [Date] – Claim for Disruption / Loss of Productivity

Dear [Name],

**1. Introduction**
We refer to your letter dated [Date] rejecting our disruption claim and requesting further information.

**2. Scope of Response**
This response addresses the disruption claim only. It does not address Extension of Time or cost claims associated with delay. We reserve our position on all other matters.

**3. Primary Position – Factual Distinction**
While it is normal for the Authority to issue instructions during the course of the works, the volume, frequency, and cumulative nature of the instructions issued between [Month] and [Month] created working conditions that were materially different from those reasonably anticipated.

The repeated changes and interference significantly disrupted the planned sequence of work, resulting in loss of productivity that would not have occurred under normal conditions.

**4. Information Provided**
We confirm the following:
- A total of [X] instructions were issued during the relevant period.
- These instructions affected work in [specific areas — kept general].

A detailed analysis of the impact on productivity will be submitted in due course.

**5. Reservation of Rights**
The Contractor maintains its entitlement to compensation for disruption. We reserve all rights and remedies under the Contract and at law.

Yours faithfully,
[Name]
[Position]

---

## Example 4: Combined EOT + Disruption Claim

### Scenario
The Contractor experienced both delay to completion (EOT) and loss of productivity (disruption) from the same series of events — multiple instructions and repeated interference. The Authority rejected the combined claim.

### Strategy Worksheet

| Dimension | Decision |
|---|---|
| **Situation** | Responding to rejection of combined EOT + disruption claim |
| **Scope** | Address both but keep them clearly separated; avoid cost quantification |
| **Direction** | Primary: Factual Distinction (cumulative/abnormal). Fallback: Textual Interpretation + Concede-then-Distinguish |
| **Argument** | Factual Distinction (primary for both heads) |
| **Disclosure** | Precise: key dates + notice dates. General: impact on both time and productivity. Defer: programme analysis + productivity calculations |
| **Architecture** | Risk Allocation Rebuttal with clear EOT/Disruption separation |
| **Risk** | Confusion between the two heads; "normal risk" argument; proving both from same events |

### Sample Response

**Subject:** Response to Letter dated [Date] – Combined Claim for Extension of Time and Disruption

Dear [Name],

**1. Introduction**
We refer to your letter dated [Date] rejecting our combined claim for Extension of Time and disruption.

**2. Scope of Response**
This response addresses both the Extension of Time and disruption aspects of the claim. We have kept the two elements separate for clarity. We reserve our position on costs and all other matters.

**3. Extension of Time – Primary Position**
The events (multiple instructions and interference) impacted the critical path of the works. Notice was given in accordance with the Contract once the delaying effect became apparent. The Contractor is entitled to an Extension of Time.

**4. Disruption – Primary Position**
In addition to the delay, the same events caused significant loss of productivity. The volume and cumulative nature of the instructions and interference created working conditions materially different from normal. This resulted in the workforce performing less efficiently than planned.

**5. Information Provided**
We provide the following:
- Key dates of the relevant instructions and events.
- Confirmation of notices submitted.
- High-level explanation of both the delay to the programme and the loss of productivity.

Detailed programme analysis and productivity assessment will be submitted within [X] weeks.

**6. Reservation of Rights**
The Contractor maintains its entitlement to both an Extension of Time and compensation for disruption. We reserve all rights and remedies under the Contract and at law.

Yours faithfully,
[Name]
[Position]

---

## Comparison: EOT vs Disruption vs Combined

| Aspect | EOT Claim | Disruption Claim | Combined |
|---|---|---|---|
| **Focus** | Delay to completion (critical path) | Loss of productivity (efficiency) | Both |
| **Strongest argument** | Textual Interpretation or Factual Distinction on notice/awareness | Factual Distinction on cumulative effect | Factual Distinction for both heads |
| **Disclosure focus** | Dates, notices, critical path | Volume/frequency of instructions | Both |
| **Core risk** | Notice timing, causation | Normal vs abnormal conditions | Confusion between the two heads |
| **Architecture** | Risk Allocation + Chronology | Risk Allocation (normal vs abnormal) | Risk Allocation with clear separation |
| **Key rule** | Keep separate from disruption | Keep separate from EOT | Structure response with clear headings |

---

*This is a workflow and analysis aid only. It does not constitute legal advice. Users should verify all information independently and seek qualified legal counsel.*


path: scripts/strategy_advisor.py
content: #!/usr/bin/env python3
"""
strategy_advisor.py — Strategic Planning Framework
Construction Claim Strategy Skill v1.7.6

Sits BEFORE clause selection. Helps plan the direction, scope, and
architecture of a claim response before deciding which clauses to cite.

The 7-Dimension methodology is contract-form neutral. It works with
PSSCOC, FIDIC, NEC, SIA, JCT, and bespoke contracts. The bundled
examples use PSSCOC 2014 (7th Edition) clause references.

Usage:
    python3 scripts/strategy_advisor.py
    python3 scripts/strategy_advisor.py --file input.json --output strategy.md

Non-interactive mode (primary use case):
    Provide a JSON file with situation details; generates a strategy report.

Interactive mode:
    Guided wizard that walks through all 7 strategy dimensions.

Output formats:
    --format md (default)
    --format txt
    --output <filename>
    --file <input.json>         Non-interactive: read from JSON
    --save-strategy <path>      Dump answered strategy as JSON
"""

import argparse
import json
import sys
import os
from datetime import datetime

# ─────────────────────────────────────────────
# VERSION
# ─────────────────────────────────────────────

SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
if SCRIPT_DIR not in sys.path:
    sys.path.insert(0, SCRIPT_DIR)

from version import VERSION

DIVIDER = "━" * 52
THIN_DIVIDER = "─" * 52


# ═══════════════════════════════════════════════
# 1. STRATEGY REFERENCE DATA
# ═══════════════════════════════════════════════

# ── 1A. Argument types ranked by strength ──
# For construction contracts (all forms)

ARGUMENT_TYPES = [
    {
        "rank": 1,
        "name": "Textual Interpretation",
        "strength": "Strongest",
        "description": (
            "Argue from the actual clause wording. Identify what the clause "
            "presupposes, what it expressly covers, and where the factual "
            "situation falls outside its scope or premise."
        ),
        "example": (
            "Clause 12.5 permits the Employer to engage other contractors "
            "on Site, but the clause does not transfer to the Contractor "
            "the risk of delay caused by acts or omissions of such other "
            "contractors. The EOT entitlement arises under Clause 14.2(m)."
        ),
        "when_to_use": (
            "Always start here. If you can win on the text, you don't need "
            "anything else. Courts and contract administrators prefer textual arguments."
        ),
    },
    {
        "rank": 2,
        "name": "Factual Distinction",
        "strength": "Strong",
        "description": (
            "Show that the factual situation exceeds the clause's scope or "
            "premise. The clause applies generally, but THIS situation is "
            "materially different from what was contemplated."
        ),
        "example": (
            "Clause 12.5 contemplates the Contractor affording 'all "
            "reasonable facilities' to other contractors in the ordinary "
            "course. Where the other contractor's delay was caused by the "
            "Employer's own coordination failure, the situation exceeds "
            "what Clause 12.5 contemplates."
        ),
        "when_to_use": (
            "When the text is broad but the facts are extraordinary. "
            "Pairs well with textual interpretation as a 1–2 punch."
        ),
    },
    {
        "rank": 3,
        "name": "Concede-then-Distinguish",
        "strength": "Moderate-Strong",
        "description": (
            "Acknowledge that the clause applies in ordinary circumstances, "
            "then distinguish THIS case as extraordinary. Disarms the other "
            "side and shows good faith."
        ),
        "example": (
            "The Contractor acknowledges that Clause 12.5 applies in "
            "ordinary circumstances and accepts its coordination obligations. "
            "However, the present delay did not arise from ordinary interface "
            "risk — it arose from the SO's direction which materially "
            "affected the Contractor's planned access and sequence of works."
        ),
        "when_to_use": (
            "For risk-allocation rebuttals. Never lead with 'the clause "
            "doesn't apply' — it antagonises the certifier. Concede the "
            "ordinary application first, then distinguish."
        ),
    },
    {
        "rank": 4,
        "name": "Implied Terms / Prevention Principle",
        "strength": "Weakest",
        "description": (
            "Argue that the contract contains implied terms or that the "
            "prevention principle bars the other party. In many jurisdictions, "
            "courts are reluctant to imply terms when express provisions "
            "exist. Standard form contracts with detailed risk allocation "
            "clauses — implied terms will usually get shut down."
        ),
        "example": (
            "There is an implied obligation not to prevent the Contractor "
            "from performing. (Weak — only use if express clauses fail.)"
        ),
        "when_to_use": (
            "Last resort only. If you're reaching for implied terms when "
            "express clauses exist, your primary arguments are probably weak. "
            "Consider whether the claim is viable at all."
        ),
    },
]


# ── 1B. Disclosure control levels ──

DISCLOSURE_LEVELS = {
    "state_precisely": {
        "label": "State Precisely",
        "description": "Documented facts with letter references, clause numbers, legal reasoning.",
        "examples": [
            "Other contractor commenced late on [date] (ref. Contractor's letter ref. [XXX])",
            "EOT clause for acts/omissions of other contractors — Clause 14.2(m)",
            "Contractor's notice ref. [XXX] dated [date] issued under Clause 14.3",
        ],
    },
    "keep_general": {
        "label": "Keep General",
        "description": (
            "Operational details (zones, quantities), dates without written "
            "record, internal arrangements. Use general language to preserve "
            "flexibility."
        ),
        "examples": [
            "'multiple work areas within and outside the Site' (not Zone A, Zone B)",
            "'resequencing of works' (not specific programme activities)",
            "'approximately [date]' for verbal/informal communications",
        ],
    },
    "defer": {
        "label": "Defer to Claim Report",
        "description": (
            "Full quantification, detailed delay analysis, cost breakdown, "
            "programme impact. Reserve for the Notified Claim Report or "
            "subsequent submissions."
        ),
        "examples": [
            "Detailed delay analysis with critical path impact",
            "Cost breakdown with quantities, rates, invoices",
            "Zone-by-zone production records",
            "Programme comparison (baseline vs actual vs impacted)",
        ],
    },
}


# ── 1C. Response architecture patterns ──

RESPONSE_PATTERNS = {
    "standard_rebuttal": {
        "name": "Standard Certifier Query Response",
        "steps": [
            "Acknowledge the certifier's position / question",
            "Pivot to Contractor's primary contractual reliance",
            "State primary argument (textual interpretation)",
            "Reserve fallback clause(s) without elaborating",
            "Close cooperatively",
        ],
        "when": (
            "Default pattern for responding to certifier queries. Works for "
            "most items in a request-for-information letter."
        ),
    },
    "risk_allocation_rebuttal": {
        "name": "Risk Allocation Rebuttal (Concede-then-Distinguish)",
        "steps": [
            "Concede the ordinary application of the risk clause",
            "Distinguish the extraordinary facts of THIS case",
            "Provide factual support (before/after, what changed)",
            "State legal conclusion (clause covers X, this is Y)",
            "Show mitigation evidence (demonstrates good faith)",
            "Close cooperatively — accept ordinary risk, maintain this is extraordinary",
        ],
        "when": (
            "When the certifier points to a specific risk-allocation clause "
            "(e.g., a clause allocating interface risk to the Contractor) "
            "and says the risk is yours. Never "
            "lead with 'the clause doesn't apply'."
        ),
    },
    "chronology_response": {
        "name": "Chronology / Details Response",
        "steps": [
            "State what is known with exact dates and references",
            "Flag items still being compiled (don't hedge documented facts)",
            "Commit to supplementing in the Notified Claim Report",
            "Reserve right to provide further details",
        ],
        "when": (
            "When asked for chronology, details, or documentary evidence. "
            "Provide what you have, hedge only what's genuinely uncertain, "
            "defer the rest."
        ),
    },
    "cost_claim_response": {
        "name": "Cost Claim Response (Pre-Quantification)",
        "steps": [
            "Identify the contractual basis for cost recovery (e.g., Cl. 63.1)",
            "List heads of claim without quantifying",
            "State that the disruption is ongoing / costs are being assessed",
            "Commit to detailed breakdown in the Notified Claim Report",
            "Reserve right to supplement",
        ],
        "when": (
            "When asked for cost breakdowns before you're ready to quantify. "
            "Name the heads of claim to show awareness, but don't lock in "
            "numbers prematurely."
        ),
    },
    "reservation_close": {
        "name": "Reservation of Rights Closing",
        "steps": [
            "State that submission is on an interim / without prejudice basis",
            "Reserve all rights, remedies, claims, and entitlements",
            "Under the Contract, at law, or otherwise",
            "Commit to cooperation",
        ],
        "when": "Always. Every substantive response should end with a reservation.",
    },
}


# ── 1D. Scope control patterns ──

SCOPE_PATTERNS = {
    "limit_to_letter": {
        "name": "Limit Response to Matters Raised",
        "description": (
            "Respond only to the specific items raised in the letter being "
            "replied to. Do not volunteer information about topics not yet "
            "addressed by the other side."
        ),
        "anti_pattern": (
            "Volunteering information about topics the certifier hasn't "
            "asked about yet. E.g., including a mitigation proposal "
            "narrative when the Employer's letter only replies to the initial "
            "notice, not the mitigation request."
        ),
        "check": "Which letter(s) are we replying to? What did they specifically ask?",
    },
    "preserve_future_claims": {
        "name": "Preserve Future Claims",
        "description": (
            "Don't close doors. Use 'reserves its position' and 'without "
            "prejudice' to keep options open for claims not yet fully "
            "developed."
        ),
        "anti_pattern": (
            "Making definitive statements that could be used against you "
            "later. E.g., 'the only delay was X' when there may be other "
            "delay events not yet notified."
        ),
        "check": "Are we making any absolute statements that could limit future claims?",
    },
    "dont_name_specifics_early": {
        "name": "Keep Operational Details General",
        "description": (
            "Don't name specific zones, quantities, or internal arrangements "
            "in initial replies. Once named in writing, you're locked in."
        ),
        "anti_pattern": (
            "Naming 'Zone A' and 'Zone B' in the initial reply. If "
            "boundaries shift during assessment, you have a consistency "
            "problem. The Employer will immediately follow up with zone-by-zone "
            "breakdowns."
        ),
        "check": "Are we naming anything specific that we might need to adjust later?",
    },
}


# ── 1E. Risk assessment checklist ──

RISK_CHECKLIST = [
    {
        "category": "Counter-Arguments",
        "questions": [
            "What will the other party argue in response?",
            "Which clauses might they cite to rebut our position?",
            "Are there any contractual provisions that explicitly allocate this risk to us?",
            "Can they argue we failed to mitigate?",
        ],
    },
    {
        "category": "Weak Points",
        "questions": [
            "Is our notice timing vulnerable? (Late notice = potential time-bar.)",
            "Are there gaps in our contemporaneous records?",
            "Did we create any inconsistencies in prior correspondence?",
            "Are we relying on verbal communications without written confirmation?",
        ],
    },
    {
        "category": "Timing Risks",
        "questions": [
            "What is the response deadline?",
            "Is the disruption still ongoing? (Affects quantification.)",
            "Are there parallel claims or notices that interact with this one?",
            "Could delay in responding weaken our position or trigger time-bar arguments?",
        ],
    },
    {
        "category": "Disclosure Risks",
        "questions": [
            "Are we volunteering anything the other side hasn't asked about?",
            "Could any statement be used against us in a future dispute?",
            "Are we prematurely quantifying before records are complete?",
            "Are we naming specifics (zones, dates, quantities) we might need to change?",
        ],
    },
]


# ── 1F. Situation triggers ──

SITUATION_TYPES = {
    "1": "Responding to the certifier's request for further information",
    "2": "Initiating a new claim / notice",
    "3": "Responding to a rejection of our claim",
    "4": "Responding to a counter-claim / back-charge",
    "5": "Preparing for adjudication / arbitration",
    "6": "Pre-emptive strategy (anticipating a dispute)",
    "7": "Other",
}


# ═══════════════════════════════════════════════
# 2. INTERACTIVE MODE
# ═══════════════════════════════════════════════

def _prompt_choice(options, allow_skip=False):
    """Prompt user to select from numbered options dict."""
    for key, label in options.items():
        print(f"  {key:>2}. {label}")
    print()
    while True:
        raw = input("Enter number: ").strip()
        if allow_skip and raw == "":
            return ""
        if raw in options:
            return raw
        print(f"  ⚠️ Invalid. Enter one of: {', '.join(options.keys())}")


def _prompt_text(label, allow_skip=False):
    """Prompt for free text."""
    hint = " (or press Enter to skip)" if allow_skip else ""
    return input(f"{label}{hint}: ").strip()



def interactive_strategy():
    """Walk through all 7 strategy dimensions interactively."""
    print()
    print(DIVIDER)
    print(" STRATEGY ADVISOR — Interactive Mode")
    print(DIVIDER)
    print()
    print("This wizard helps you plan your strategic approach BEFORE")
    print("selecting clauses or drafting a response.")
    print()

    strategy = {}

    # ── Dimension 1: Situation Assessment ──
    print(THIN_DIVIDER)
    print(" 1. SITUATION ASSESSMENT")
    print(THIN_DIVIDER)
    print()
    print("What are we dealing with?")
    print()
    sit_key = _prompt_choice(SITUATION_TYPES)
    strategy["situation_type"] = SITUATION_TYPES[sit_key]
    print()

    strategy["other_side_position"] = _prompt_text(
        "What is the other side's position / what did they say?"
    )
    strategy["trigger_event"] = _prompt_text(
        "What triggered this? (e.g., letter ref, event, instruction)"
    )
    strategy["responding_to_letters"] = _prompt_text(
        "Which letter(s) are we replying to? (refs and dates)"
    )

    # ── Dimension 2: Scope Control ──
    print()
    print(THIN_DIVIDER)
    print(" 2. SCOPE CONTROL")
    print(THIN_DIVIDER)
    print()
    strategy["in_scope"] = _prompt_text(
        "What is IN scope for this response?"
    )
    strategy["out_of_scope"] = _prompt_text(
        "What should we NOT volunteer? (topics not yet raised)", allow_skip=True
    )
    strategy["future_claims_to_preserve"] = _prompt_text(
        "Any future claims / positions to preserve?", allow_skip=True
    )

    # ── Dimension 3: Direction Decision ──
    print()
    print(THIN_DIVIDER)
    print(" 3. DIRECTION DECISION")
    print(THIN_DIVIDER)
    print()
    strategy["primary_argument"] = _prompt_text(
        "Primary argument / clause (your strongest position)"
    )
    strategy["fallback_argument"] = _prompt_text(
        "Fallback argument / clause (reserve position)", allow_skip=True
    )
    strategy["clauses_to_avoid"] = _prompt_text(
        "Any clauses to AVOID citing? (and why)", allow_skip=True
    )

    # ── Dimension 4: Argument Strategy ──
    print()
    print(THIN_DIVIDER)
    print(" 4. ARGUMENT STRATEGY")
    print(THIN_DIVIDER)
    print()
    print("Argument types ranked by strength:")
    print()
    for at in ARGUMENT_TYPES:
        print(f"  {at['rank']}. {at['name']} ({at['strength']})")
    print()
    strategy["chosen_argument_type"] = _prompt_text(
        "Which argument type will you lead with? (number or name)"
    )
    strategy["argument_notes"] = _prompt_text(
        "Notes on argument approach", allow_skip=True
    )

    # ── Dimension 5: Disclosure Control ──
    print()
    print(THIN_DIVIDER)
    print(" 5. DISCLOSURE CONTROL")
    print(THIN_DIVIDER)
    print()
    print("What level of detail at this stage?")
    for key, level in DISCLOSURE_LEVELS.items():
        print(f"\n  [{key}] {level['label']}")
        print(f"    {level['description']}")
    print()
    strategy["state_precisely"] = _prompt_text(
        "What should be stated precisely? (documented facts, clause refs)",
        allow_skip=True
    )
    strategy["keep_general"] = _prompt_text(
        "What should be kept general? (operational details, zones, quantities)",
        allow_skip=True
    )
    strategy["defer_items"] = _prompt_text(
        "What should be deferred to the Claim Report?",
        allow_skip=True
    )

    # ── Dimension 6: Response Architecture ──
    print()
    print(THIN_DIVIDER)
    print(" 6. RESPONSE ARCHITECTURE")
    print(THIN_DIVIDER)
    print()
    print("Available response patterns:")
    for key, pattern in RESPONSE_PATTERNS.items():
        print(f"\n  [{key}]  {pattern['name']}")
        print(f"    When: {pattern['when']}")
    print()
    strategy["chosen_pattern"] = _prompt_text(
        "Which pattern(s) will you use? (name or key)", allow_skip=True
    )
    strategy["architecture_notes"] = _prompt_text(
        "Notes on response structure", allow_skip=True
    )

    # ── Dimension 7: Risk Assessment ──
    print()
    print(THIN_DIVIDER)
    print(" 7. RISK ASSESSMENT")
    print(THIN_DIVIDER)
    print()
    strategy["counter_arguments"] = _prompt_text(
        "Expected counter-arguments from the other side", allow_skip=True
    )
    strategy["weak_points"] = _prompt_text(
        "Known weak points in our position", allow_skip=True
    )
    strategy["timing_risks"] = _prompt_text(
        "Timing risks (deadlines, ongoing events)", allow_skip=True
    )
    strategy["response_deadline"] = _prompt_text(
        "Response deadline (specific calendar date, e.g. 2026-04-22 \u2014 "
        "calculate using the construction-law SOP calculator if applicable)",
        allow_skip=True
    )

    return strategy


# ═══════════════════════════════════════════════
# 3. REPORT GENERATOR
# ═══════════════════════════════════════════════

def generate_report(strategy, fmt="md"):
    """Generate a strategy report from a strategy dict."""
    lines = []

    def heading(level, text):
        if fmt == "md":
            lines.append(f"{'#' * level} {text}")
        else:
            lines.append(text)
            lines.append("=" * len(text) if level <= 2 else "-" * len(text))

    def bullet(text, indent=0):
        prefix = "  " * indent
        if fmt == "md":
            lines.append(f"{prefix}- {text}")
        else:
            lines.append(f"{prefix}• {text}")

    def para(text):
        lines.append(text)

    def blank():
        lines.append("")

    def field(label, value, indent=0):
        if value:
            bullet(f"**{label}:** {value}" if fmt == "md" else f"{label}: {value}", indent)

    # ── Title ──
    lines.append(DIVIDER)
    lines.append(" STRATEGY REPORT")
    lines.append(DIVIDER)
    blank()
    para(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}")
    para(f"Strategy Advisor v{VERSION}")
    blank()

    # ── 1. Situation Assessment ──
    heading(2, "1. Situation Assessment")
    blank()
    field("Type", strategy.get("situation_type", ""))
    field("Other side's position", strategy.get("other_side_position", ""))
    field("Trigger", strategy.get("trigger_event", ""))
    field("Responding to", strategy.get("responding_to_letters", ""))
    blank()

    # ── 2. Scope Control ──
    heading(2, "2. Scope Control")
    blank()
    field("In scope", strategy.get("in_scope", ""))
    field("Out of scope / Do NOT volunteer", strategy.get("out_of_scope", ""))
    field("Future claims to preserve", strategy.get("future_claims_to_preserve", ""))
    blank()

    # Reference: scope control patterns
    if fmt == "md":
        para("**Scope Control Checklist:**")
    else:
        para("Scope Control Checklist:")
    for key, pattern in SCOPE_PATTERNS.items():
        bullet(f"{pattern['name']}: {pattern['check']}")
    blank()

    # ── 3. Direction Decision ──
    heading(2, "3. Direction Decision")
    blank()
    field("Primary argument / clause", strategy.get("primary_argument", ""))
    field("Fallback argument / clause", strategy.get("fallback_argument", ""))
    field("Clauses to AVOID", strategy.get("clauses_to_avoid", ""))
    blank()

    # ── 4. Argument Strategy ──
    heading(2, "4. Argument Strategy")
    blank()
    field("Chosen argument type", strategy.get("chosen_argument_type", ""))
    field("Notes", strategy.get("argument_notes", ""))
    blank()

    if fmt == "md":
        para("**Argument Types (ranked by strength):**")
    else:
        para("Argument Types (ranked by strength):")
    blank()
    for at in ARGUMENT_TYPES:
        bullet(f"Rank {at['rank']}: {at['name']} ({at['strength']})")
        bullet(f"When: {at['when_to_use']}", indent=1)
    blank()

    # ── 5. Disclosure Control ──
    heading(2, "5. Disclosure Control")
    blank()
    field("State precisely", strategy.get("state_precisely", ""))
    field("Keep general", strategy.get("keep_general", ""))
    field("Defer to Claim Report", strategy.get("defer_items", ""))
    blank()

    if fmt == "md":
        para("**Disclosure Level Reference:**")
    else:
        para("Disclosure Level Reference:")
    for key, level in DISCLOSURE_LEVELS.items():
        bullet(f"{level['label']}: {level['description']}")
        for ex in level["examples"]:
            bullet(ex, indent=1)
    blank()

    # ── 6. Response Architecture ──
    heading(2, "6. Response Architecture")
    blank()
    field("Chosen pattern(s)", strategy.get("chosen_pattern", ""))
    field("Notes", strategy.get("architecture_notes", ""))
    blank()

    if fmt == "md":
        para("**Available Response Patterns:**")
    else:
        para("Available Response Patterns:")
    blank()
    for key, pattern in RESPONSE_PATTERNS.items():
        if fmt == "md":
            bullet(f"**{pattern['name']}**")
        else:
            bullet(pattern["name"])
        for i, step in enumerate(pattern["steps"], 1):
            bullet(f"Step {i}: {step}", indent=1)
        bullet(f"When: {pattern['when']}", indent=1)
        blank()

    # ── 7. Risk Assessment ──
    heading(2, "7. Risk Assessment")
    blank()
    field("Expected counter-arguments", strategy.get("counter_arguments", ""))
    field("Known weak points", strategy.get("weak_points", ""))
    field("Timing risks", strategy.get("timing_risks", ""))
    field("Response deadline", strategy.get("response_deadline", ""))
    blank()

    if fmt == "md":
        para("**Risk Checklist:**")
    else:
        para("Risk Checklist:")
    for section in RISK_CHECKLIST:
        bullet(section["category"])
        for q in section["questions"]:
            bullet(q, indent=1)
    blank()

    # ── Footer ──
    lines.append(THIN_DIVIDER)
    para(f"Generated by Strategy Advisor v{VERSION}")
    para("This is a strategic planning aid only. It is not legal advice.")
    lines.append(THIN_DIVIDER)

    return "\n".join(lines)


# ═══════════════════════════════════════════════
# 4. CLI
# ═══════════════════════════════════════════════

def main():
    parser = argparse.ArgumentParser(
        prog="strategy_advisor",
        description=(
            "Strategy Advisor — Strategic planning framework for construction "
            "claim responses. Plan your direction, scope, and argument strategy "
            "BEFORE selecting clauses."
        ),
    )
    parser.add_argument(
        "--file",
        metavar="INPUT_JSON",
        help="Non-interactive: read strategy inputs from a JSON file.",
    )
    parser.add_argument(
        "--output", "-o",
        metavar="FILE",
        help="Write report to file instead of stdout.",
    )
    parser.add_argument(
        "--format", "-f",
        choices=["md", "txt"],
        default="md",
        help="Output format (default: md).",
    )
    parser.add_argument(
        "--save-strategy",
        metavar="PATH",
        help="Save the strategy data as JSON for reuse.",
    )
    parser.add_argument(
        "--reference",
        action="store_true",
        help="Print all reference tables (argument types, patterns, etc.) and exit.",
    )
    parser.add_argument(
        "--version",
        action="version",
        version=f"Strategy Advisor v{VERSION}",
    )

    def _safe_write(path, content, label="file"):
        """Write *content* to *path*, exiting cleanly on permission/OS errors."""
        try:
            with open(path, "w", encoding="utf-8") as fh:
                fh.write(content)
        except (PermissionError, OSError) as e:
            print(f"❌ Cannot write {label}: {e}", file=sys.stderr)
            sys.exit(1)

    args = parser.parse_args()

    # ── Reference mode: dump all tables ──
    if args.reference:
        _print_reference(args.format)
        return

    # ── Non-interactive mode ──
    if args.file:
        try:
            with open(args.file, "r", encoding="utf-8") as fh:
                strategy = json.load(fh)
        except FileNotFoundError:
            print(f"❌ File not found: {args.file}", file=sys.stderr)
            sys.exit(1)
        except PermissionError:
            print(f"❌ Permission denied: {args.file}", file=sys.stderr)
            sys.exit(1)
        except json.JSONDecodeError as e:
            print(f"❌ Invalid JSON in {args.file}: {e}", file=sys.stderr)
            sys.exit(1)

        if not isinstance(strategy, dict):
            print(
                f"❌ Expected a JSON object (dict) in {args.file}, "
                f"got {type(strategy).__name__}.",
                file=sys.stderr,
            )
            sys.exit(1)

        # Warn on unrecognised keys
        _KNOWN_KEYS = {
            "situation_type", "other_side_position", "trigger_event",
            "responding_to_letters", "in_scope", "out_of_scope",
            "future_claims_to_preserve", "primary_argument",
            "fallback_argument", "clauses_to_avoid",
            "chosen_argument_type", "argument_notes",
            "state_precisely", "keep_general", "defer_items",
            "chosen_pattern", "architecture_notes",
            "counter_arguments", "weak_points", "timing_risks",
            "response_deadline",
        }
        _REQUIRED_KEYS = {
            "situation_type", "other_side_position", "trigger_event",
            "primary_argument", "chosen_argument_type",
            "chosen_pattern",
        }
        missing = _REQUIRED_KEYS - set(strategy.keys())
        if missing:
            print(
                f"❌ Missing required key(s) in {args.file}: "
                f"{', '.join(sorted(missing))}\n"
                f"   Required fields: {', '.join(sorted(_REQUIRED_KEYS))}",
                file=sys.stderr,
            )
            sys.exit(1)
        unknown = set(strategy.keys()) - _KNOWN_KEYS
        if unknown:
            print(
                f"⚠️  Unrecognised key(s) in input (ignored): "
                f"{', '.join(sorted(unknown))}",
                file=sys.stderr,
            )

        report = generate_report(strategy, fmt=args.format)
        if args.output:
            _safe_write(args.output, report, label=f"output file '{args.output}'")
            print(f"✅ Strategy report written to {args.output}")
        else:
            print(report)
        if args.save_strategy:
            _safe_write(
                args.save_strategy,
                json.dumps(strategy, indent=2, ensure_ascii=False),
                label=f"strategy file '{args.save_strategy}'",
            )
            print(f"✅ Strategy data saved to {args.save_strategy}")
        return

    # ── Interactive mode ──
    try:
        strategy = interactive_strategy()
    except (KeyboardInterrupt, EOFError):
        print("\n\n⚠️ Strategy session cancelled.")
        sys.exit(1)

    report = generate_report(strategy, fmt=args.format)

    if args.output:
        _safe_write(args.output, report, label=f"output file '{args.output}'")
        print(f"\n✅ Strategy report written to {args.output}")
    else:
        print()
        print(report)

    if args.save_strategy:
        _safe_write(
            args.save_strategy,
            json.dumps(strategy, indent=2, ensure_ascii=False),
            label=f"strategy file '{args.save_strategy}'",
        )
        print(f"✅ Strategy data saved to {args.save_strategy}")


def _print_reference(fmt="md"):
    """Print all reference tables for Claude / agent use."""
    lines = []

    def heading(level, text):
        if fmt == "md":
            lines.append(f"{'#' * level} {text}")
        else:
            lines.append(text)
            lines.append("=" * len(text) if level <= 2 else "-" * len(text))

    def bullet(text, indent=0):
        prefix = "  " * indent
        lines.append(f"{prefix}- {text}" if fmt == "md" else f"{prefix}• {text}")

    def blank():
        lines.append("")

    heading(1, "Strategy Advisor — Reference Tables")
    blank()
    lines.append(f"Version: {VERSION}")
    blank()

    # Argument types
    heading(2, "Argument Types (Ranked by Strength)")
    blank()
    for at in ARGUMENT_TYPES:
        heading(3, f"Rank {at['rank']}: {at['name']} ({at['strength']})")
        blank()
        lines.append(at["description"])
        blank()
        bullet(f"Example: {at['example']}")
        bullet(f"When to use: {at['when_to_use']}")
        blank()

    # Disclosure levels
    heading(2, "Disclosure Control Levels")
    blank()
    for key, level in DISCLOSURE_LEVELS.items():
        heading(3, level["label"])
        blank()
        lines.append(level["description"])
        blank()
        for ex in level["examples"]:
            bullet(ex)
        blank()

    # Response patterns
    heading(2, "Response Architecture Patterns")
    blank()
    for key, pattern in RESPONSE_PATTERNS.items():
        heading(3, pattern["name"])
        blank()
        for i, step in enumerate(pattern["steps"], 1):
            bullet(f"Step {i}: {step}")
        blank()
        lines.append(f"When: {pattern['when']}")
        blank()

    # Scope control
    heading(2, "Scope Control Patterns")
    blank()
    for key, pattern in SCOPE_PATTERNS.items():
        heading(3, pattern["name"])
        blank()
        lines.append(pattern["description"])
        blank()
        bullet(f"Anti-pattern: {pattern['anti_pattern']}")
        bullet(f"Check: {pattern['check']}")
        blank()

    # Risk checklist
    heading(2, "Risk Assessment Checklist")
    blank()
    for section in RISK_CHECKLIST:
        heading(3, section["category"])
        blank()
        for q in section["questions"]:
            bullet(q)
        blank()

    # Situation types
    heading(2, "Situation Types")
    blank()
    for key, label in SITUATION_TYPES.items():
        bullet(f"{key}. {label}")
    blank()

    print("\n".join(lines))


if __name__ == "__main__":
    main()


path: scripts/version.py
content: """
Single source of truth for the construction-claim-strategy skill version.
"""

VERSION = "1.7.6"

def footer(generator_name: str = "Construction Claim Strategy") -> str:
    """Standard footer for generated artefacts."""
    return f"*Generated by {generator_name} v{VERSION}*"


path: tests/test_smoke.py
content: """
Smoke test for strategy_advisor.py.

Tests the script by importing main() directly and patching sys.argv,
avoiding external process invocation entirely. This keeps the CLI
smoke-test intent while satisfying static-analysis scanners.

Checks that:
  - --reference exits cleanly and prints non-empty output
  - --file mode exits cleanly
  - the output file is created and non-empty
  - the output contains all 7 dimension headers
  - the script contains no forbidden imports

This is intentionally minimal. It catches the most common breakages:
import errors, missing files, schema regressions, and major output
structural changes. It is not a substitute for unit tests of the
underlying logic.

Run from the package root:
    python3 -m unittest tests.test_smoke
    python3 -m pytest tests/test_smoke.py  (if pytest is installed)
"""

import io
import os
import sys
import tempfile
import unittest
from contextlib import redirect_stdout, redirect_stderr
from pathlib import Path
from unittest.mock import patch


PACKAGE_ROOT = Path(__file__).resolve().parent.parent
SCRIPT = PACKAGE_ROOT / "scripts" / "strategy_advisor.py"
SAMPLE_INPUT = PACKAGE_ROOT / "examples" / "strategy_input.json"

# Ensure scripts/ is importable
SCRIPTS_DIR = str(PACKAGE_ROOT / "scripts")
if SCRIPTS_DIR not in sys.path:
    sys.path.insert(0, SCRIPTS_DIR)

from strategy_advisor import main, VERSION

EXPECTED_DIMENSION_HEADERS = [
    "Situation Assessment",
    "Scope Control",
    "Direction Decision",
    "Argument Strategy",
    "Disclosure Control",
    "Response Architecture",
    "Risk Assessment",
]


class StrategyAdvisorSmokeTest(unittest.TestCase):

    def setUp(self):
        self.assertTrue(SCRIPT.exists(), f"Script not found: {SCRIPT}")
        self.assertTrue(
            SAMPLE_INPUT.exists(),
            f"Sample input not found: {SAMPLE_INPUT}",
        )

    def _run_cli(self, argv):
        """Run main() with patched sys.argv, capturing stdout/stderr."""
        out = io.StringIO()
        err = io.StringIO()
        with patch.object(sys, "argv", argv), \
             redirect_stdout(out), redirect_stderr(err):
            try:
                main()
                code = 0
            except SystemExit as e:
                code = int(e.code) if e.code is not None else 0
        return code, out.getvalue(), err.getvalue()

    def test_reference_mode_runs(self):
        """`--reference` should run and print non-empty output to stdout."""
        code, stdout, stderr = self._run_cli(
            ["strategy_advisor.py", "--reference"]
        )
        self.assertEqual(
            code, 0,
            f"--reference exited non-zero. stderr:\n{stderr}",
        )
        self.assertTrue(
            stdout.strip(),
            "--reference produced empty output",
        )

    def test_file_mode_produces_report(self):
        """`--file` mode should generate a report containing all 7 dimensions."""
        with tempfile.NamedTemporaryFile(
            mode="w", suffix=".md", delete=False
        ) as tmp:
            output_path = tmp.name

        try:
            code, stdout, stderr = self._run_cli([
                "strategy_advisor.py",
                "--file", str(SAMPLE_INPUT),
                "--output", output_path,
            ])
            self.assertEqual(
                code, 0,
                f"--file mode exited non-zero. stderr:\n{stderr}",
            )

            self.assertTrue(
                os.path.exists(output_path),
                "Output file was not created",
            )
            with open(output_path, "r", encoding="utf-8") as f:
                report = f.read()

            self.assertTrue(report.strip(), "Output report is empty")

            for header in EXPECTED_DIMENSION_HEADERS:
                self.assertIn(
                    header, report,
                    f"Expected dimension header not found in report: {header!r}",
                )
        finally:
            if os.path.exists(output_path):
                os.unlink(output_path)

    def test_version_flag(self):
        """`--version` should print version string and exit cleanly."""
        code, stdout, stderr = self._run_cli(
            ["strategy_advisor.py", "--version"]
        )
        self.assertEqual(code, 0)
        self.assertIn("Strategy Advisor v", stdout + stderr)

    def test_no_forbidden_imports(self):
        """Script must not import network, subprocess, or dynamic-exec modules.

        Uses ast.parse to walk the syntax tree. Catches forbidden
        imports and dangerous built-in calls regardless of aliasing,
        whitespace, or indirection. Does not false-positive on
        comments, docstrings, or plain-English strings.

        Enforces the 'stdlib-only, no network, no subprocess' security claim
        in SKILL.md.
        """
        import ast

        FORBIDDEN_MODULES = {
            "subprocess", "socket", "requests", "httpx", "aiohttp",
            "importlib", "pickle", "marshal",
        }
        # Dotted imports: "from urllib.request import ..." etc.
        FORBIDDEN_DOTTED = {
            "urllib.request", "urllib.error",
            "http.client", "http.server",
        }
        # Bare dangerous built-in calls
        FORBIDDEN_CALLS = {"exec", "eval", "compile"}
        # Attribute calls: os.system(), pickle.loads(), etc.
        FORBIDDEN_ATTR_CALLS = {
            ("os", "system"),
            ("pickle", "loads"),
            ("marshal", "loads"),
            ("importlib", "import_module"),
        }

        with open(SCRIPT, "r", encoding="utf-8") as f:
            source = f.read()

        tree = ast.parse(source, filename=str(SCRIPT))
        violations = []

        for node in ast.walk(tree):
            # import X / import X as Y
            if isinstance(node, ast.Import):
                for alias in node.names:
                    top = alias.name.split(".")[0]
                    if top in FORBIDDEN_MODULES or alias.name in FORBIDDEN_DOTTED:
                        violations.append(
                            f"  L{node.lineno}: import {alias.name}"
                        )
            # from X import Y
            elif isinstance(node, ast.ImportFrom) and node.module:
                top = node.module.split(".")[0]
                if top in FORBIDDEN_MODULES or node.module in FORBIDDEN_DOTTED:
                    violations.append(
                        f"  L{node.lineno}: from {node.module} import ..."
                    )
            # function calls
            elif isinstance(node, ast.Call):
                func = node.func
                # bare dangerous call
                if isinstance(func, ast.Name) and func.id in FORBIDDEN_CALLS:
                    violations.append(
                        f"  L{node.lineno}: {func.id}() call"
                    )
                # dotted dangerous call
                elif isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
                    pair = (func.value.id, func.attr)
                    if pair in FORBIDDEN_ATTR_CALLS:
                        violations.append(
                            f"  L{node.lineno}: {func.value.id}.{func.attr}() call"
                        )

        self.assertEqual(
            violations, [],
            "Forbidden import/call found in strategy_advisor.py:\n"
            + "\n".join(violations),
        )


if __name__ == "__main__":
    unittest.main()


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)