# Value Articulation — Extraction Plan

- **Sub-criterion:** 2.3 (Product Thinking)
- **Weight:** 12.5 pts
- **Source quote:** _"Does the README make a case for impact? Are claims quantified (time saved, cost, quality)?"_

This recipe scores how well the README articulates value — whether it makes a clear case for impact with a named audience and quantified outcomes (time / cost / quality).

---

## Extraction recipe

README-centric. The evaluator parses the README for impact claims, audience, scope coverage, and quantified outcomes.

### Signal 1 — README impact read (LLM interpretive)

Feed the LLM the full README (truncated to the first ~1000 lines) plus a list of shipped capabilities (extracted from the `mechanical_ambition` recipe's `shipped_*` fields in its `raw/mechanical-ambition-llm-read.md`, if that recipe has already run for this project):

```bash
head -1000 "$REPO/README.md" > /tmp/val-art-readme.md
```

Write the LLM read to `raw/value-articulation-llm-read.md`. The LLM emits:

```yaml
scope_breadth: N                              # number of distinct capabilities the README claims
integration_depth: "shallow" | "medium" | "deep"   # does it integrate with internal systems, external APIs, just local data?
completeness_ratio: 0.0-1.0                   # 1 − (stubs/handlers ratio) from mechanical_ambition, or inferred 1.0 if no stubs
time_saved_claim_in_readme: null | "<verbatim quote>"   # e.g. "saves 3 hours per incident triage"
audience_inferred: "internal engineers" | "support agents" | "end customers" | "unclear"
value_articulation_score: 0-5                 # 5 = crisp audience + quantified impact + scope matches claim; 0 = no value claim
one_sentence: "<LLM's one-line verdict>"
```

### Signal 2 — Proxies JSON

Aggregate into `raw/value-articulation-proxies.json`:

```json
{
  "scope_breadth": N,
  "integration_depth": "shallow|medium|deep",
  "completeness_ratio": 0.0-1.0,
  "time_saved_claim_in_readme": null|"...",
  "audience_inferred": "..."
}
```

---

## Banding (absolute)

| Band | Criteria |
| --- | --- |
| **5** | Crisp value story: named audience + quantified impact (time / cost / quality numbers) + scope matches the claim (completeness_ratio ≥ 0.85). `value_articulation_score: 5`. |
| **4** | Strong value story with one gap (quantified OR audience-specific, not both; or scope slightly short of claim). `value_articulation_score: 4`, `completeness_ratio ≥ 0.7`. |
| **3** | Value articulated but fuzzy: claim present but unquantified, OR audience generic. `value_articulation_score: 3`. |
| **2** | README mentions value in passing but no coherent story. `value_articulation_score: 2`. |
| **1** | No value claim, or README is an unmodified starter/template README. `value_articulation_score ≤ 1`. |
| **0** | Empty README. |

**Over-promise penalty:** if `completeness_ratio < 0.5` AND the README claims shipped functionality (not "WIP"), cap the band at **2** — the README is writing checks the code doesn't cash.

---

## Raw dumps

- `raw/value-articulation-llm-read.md` — LLM's full README-impact read with axis scores + verbatim quantified-claim quotes.
- `raw/value-articulation-proxies.json` — aggregated JSON (also embedded in `scorecard.yaml.value_articulation.data`).

---

## Not in scope

- Judging whether the claimed impact is realistic needs real operational/runtime data — out of scope; this recipe scores how well the README *articulates* value, not whether the claimed magnitude holds up.
- Measuring actual runtime behavior against claims — that's a separate runtime-verification pass, out of scope here.