# Phase 3 brief: building the unified capability rows

This is the exact brief the phase 3 taxonomy author received. It is kept as
part of the methodology disclosure (see `00-methodology.md`).

## Why a separate author

The person who coordinates this audit knows Cargo-Planner's product and
marketing well. Row design is where that knowledge could bias the result most:
through which rows exist, how finely an area is split, and how a requirement is
worded. So the rows are written by an author who has seen only the audit data.
Any row the coordinator later adds is recorded separately, marked with who
added it and why, and is reviewed by a person.

## Your role

You have the phase 2 audit files for eight load planning products. Merge
everything they record into one set of **requirement rows**: the unified
matrix every product will be scored against in phase 4. You are designing the
rows, not scoring products. Do not visit cargo-planner.com and do not read any
file in `/workspaces/cplweb` outside `research/market-audit/`. Within that
folder, read only:

- `00-methodology.md`
- this brief
- `02-audit-brief.md`
- `competitors/*.json` and `competitors/*.md`

Do not read anything under `work/`.

## Design rules

1. **A row is a requirement a shipper could state, with a pass condition.**
   Write it as an outcome, not a feature name.
   - Good: "The user can make an item carry at most 50 kg on top of it."
   - Bad: "Load-bearing field".

   The pass condition must be concrete enough that two auditors reading the
   same documentation would reach the same verdict.
2. **As close to binary as possible.** Where products differ in depth, split
   the area into several rows, each binary, rather than one row with levels.
   For example: "prevent rotation about the vertical axis"; "choose any subset
   of the six orientations"; "set stacking parameters that differ by
   orientation".
3. **No mechanism in the requirement.** A row must be passable both by a
   dedicated setting and by a combination of general mechanisms. Do not word a
   row after one vendor's feature. If a vendor-specific feature is a real
   capability, name the outcome it achieves.
4. **Keep enforced and reported apart.** Several products calculate something
   (axle loads, centre of gravity) without the planner respecting it while it
   builds the plan. "The plan respects X" and "the output reports X" are always
   separate rows.
5. **Every row needs an origin.** List the audit records (`product:record-id`)
   that motivated it. A row motivated by the academic constraint literature
   instead (Bortfeldt & Wäscher 2013; Silva et al.) may cite that, but mark it.
   Rows motivated only by a documented limitation or an absence are allowed,
   because they show a real gap, as long as the origin says so.
6. **Cover the whole market, not the average.** A capability only one product
   documents still gets a row. A capability every product has still gets a row;
   baseline rows are fine and should be marked `baseline: true`.
7. **Engine capability only.** Planning inputs, rules, objectives and what the
   planner's output contains. UI, integrations, pricing and deployment are out
   of scope.
8. **Include a cluster for expressiveness.** Include rows for what users can
   build themselves, based on the `generalMechanisms` sections. Examples: rules
   that select cargo by an attribute condition; user-defined attributes the
   engine acts on; class-code matrices; caps on any additive per-item value;
   combinable objectives. These rows must also be testable requirements.
9. **Clusters.** Group rows into clusters that let a reader see coverage by
   area: for example equipment geometry, fleet selection, cargo shapes,
   orientation, stacking, rules between items, positioning, weight and balance,
   sequencing and multi-drop, pallet building, objectives, expressiveness and
   output. Also tag each row with the transport modes it mainly concerns
   (`road`, `sea`, `air`, `rail`, `pallet`, `general`), so mode-specific
   coverage can be read off, for example road-freight coverage.
10. **Size.** Aim for roughly 90–130 rows. Merge records that are the same
    requirement in different words. Do not merge requirements that a product
    could pass one of and fail the other.

## Output

Write `/workspaces/cplweb/research/market-audit/03-taxonomy.json`:

```json
{
  "version": "draft-1",
  "author": "phase 3 taxonomy author (blind)",
  "clusters": [
    {
      "id": "kebab",
      "name": "",
      "description": "",
      "rows": [
        {
          "id": "cluster-short-kebab",
          "requirement": "one sentence, outcome-worded",
          "passCondition": "what documentation must show for a pass",
          "definitionNote": "footnote: scope, edge cases, what does NOT count, how it differs from neighbouring rows",
          "modes": ["general"],
          "baseline": false,
          "origin": ["product:record-id", "literature: ..."],
          "splitFrom": "if this is one row of a split area, the shared area name"
        }
      ]
    }
  ],
  "mergedRecords": "brief notes on notable merges",
  "unmappedRecords": [{ "record": "product:record-id", "reason": "why no row covers it (e.g. out of scope)" }],
  "designNotes": "decisions a reviewer should know about"
}
```

Every capability record in the audit files must either be covered by at least
one row (listed in that row's `origin`) or appear in `unmappedRecords` with a
reason. Check this with a script before you finish.

Also write `03-taxonomy.md`: a readable version with one table per cluster
(requirement, pass condition, modes) and the design notes. Its readers will
include the public, so write it neutrally.

Final reply: the number of rows per cluster, the number of unmapped records
and why, and the judgement calls you are least sure of.