@maestroagora/agora 1.3.0 → 1.5.0

package/skills/agora/references/agora-case-studies.md

@@ -0,0 +1,381 @@
+# Agora case-study authority
+
+This reference governs the `CASE_STUDY` modifier for customer success, creative portfolio, and technical implementation case studies. A real case study is an evidence-led argument about a real project. An explicit fictional mock or disclosed concept portfolio is a different evidence status with different permissions. Neither route is a chronological diary, a caption gallery, a disguised testimonial, or permission to present invention as real evidence.
+
+Select the primary Agora mode first. `CASE_STUDY` changes evidence intake, attribution, permissions, structure, and maintenance. It does not replace `SELL`, `POSITION`, or `INFORM`. Academic and clinical case reports are outside this reference.
+
+## Contents
+
+- [Choose the case family and decision](#choose-the-case-family-and-decision)
+- [Choose the evidence status](#choose-the-evidence-status)
+- [Build the evidence packet](#build-the-evidence-packet)
+- [Classify results before writing](#classify-results-before-writing)
+- [Calibrate causality and metrics](#calibrate-causality-and-metrics)
+- [Control permission and confidentiality](#control-permission-and-confidentiality)
+- [Handle quotes and testimonials](#handle-quotes-and-testimonials)
+- [Build a structured argument](#build-a-structured-argument)
+- [Use visuals as evidence](#use-visuals-as-evidence)
+- [Adapt each case family](#adapt-each-case-family)
+- [Layer the case for scanning and inspection](#layer-the-case-for-scanning-and-inspection)
+- [Compose with SCIENCE, SELL, VOICE, and GEO](#compose-with-science-sell-voice-and-geo)
+- [Maintain the case](#maintain-the-case)
+- [Refusals and failure conditions](#refusals-and-failure-conditions)
+- [Evaluation contract](#evaluation-contract)
+- [Evidence register](#evidence-register)
+
+## Choose the case family and decision
+
+Select one family:
+
+| Family | Primary focus |
+|---|---|
+| `CUSTOMER_SUCCESS` | Buyer problem, intervention, measured or reported result, attribution, and decision relevance |
+| `CREATIVE_PORTFOLIO` | Brief, constraints, insight, concept, role, decisions, execution, and evidence |
+| `TECHNICAL_IMPLEMENTATION` | System constraint, alternatives, architecture, rollout, failure modes, observed performance, and tradeoffs |
+
+Then identify the decision the case must support. A buyer may need evidence of fit. A hiring reviewer may need evidence of judgment and role. A technical evaluator may need architecture, tradeoffs, and failure behavior. A research reader may need method, source, and uncertainty.
+
+Rule [C/HOUSE]: choose a case because it proves a capability relevant to that decision, not because the subject has the largest logo. Practitioner research supports audience filtering and role clarity; the selection rule is Agora's inference. Boundary: a recognizable subject can still be relevant proof when the project itself contains the needed evidence.
+
+## Choose the evidence status
+
+Evidence status is separate from case family:
+
+| Status | Use | Invention boundary |
+|---|---|---|
+| `REAL_EVIDENCE` | A real subject, project, customer, commission, implementation, or publishable proof | Do not invent missing history, roles, artifacts, quotes, permissions, measurements, or results |
+| `FICTIONAL_MOCK` | An explicitly fictional, mock, synthetic, demo, sample, or teaching case | May invent a coherent brief, history, constraints, roles, artifacts, and illustrative results within the requested scenario |
+| `CONCEPT_PORTFOLIO` | Self-initiated, speculative, uncommissioned, or concept work | May invent the scenario or brief, but do not imply a real client, commission, approval, shipped state, research activity, or measured outcome |
+
+Use `REAL_EVIDENCE` by default whenever the request names a real project or could reasonably be read as a factual case. Use `FICTIONAL_MOCK` or `CONCEPT_PORTFOLIO` only when the user explicitly requests that status or the supplied brief already labels it that way. Fiction is not a workaround for missing evidence in a real case.
+
+In fictional work, invention is part of the assignment. Keep it legible as invention:
+
+- label the work `fictional`, `mock`, `hypothetical`, `sample`, `concept`, or `self-initiated` when an external reader could mistake it for real evidence;
+- label invented numbers and results as illustrative, simulated, or scenario assumptions;
+- never attach invented conduct, quotes, endorsements, confidential facts, or results to a real person or organization;
+- never use a real customer's identity, logo, or recognizable details to make fiction look verified;
+- never present a fictional case as product proof, customer proof, a shipped engagement, or an observed result;
+- keep academic and clinical case reports outside this reference, including fictional reports that could masquerade as medical evidence.
+
+If fictional material mixes in a real identity, source, quotation, or artifact, the real element keeps its normal attribution, permission, and truth controls. The fictional status does not dissolve those controls.
+
+Rule [HOUSE]: evidence status determines whether invention is allowed. Boundary: disclosure may be compact and channel-native, but it must be clear before a reasonable reader could rely on the work as factual evidence.
+
+## Build the evidence packet
+
+Collect or mark missing before drafting:
+
+- intended audience and desired decision;
+- subject, organization, and project;
+- time window;
+- initial condition or baseline;
+- objective;
+- constraints;
+- intervention or work performed;
+- alternatives considered and why they were rejected;
+- roles, team members, and external contributors;
+- source artifacts;
+- metrics, denominator, comparison method, and measurement owner;
+- confounders and concurrent changes;
+- customer-reported observations;
+- quote source and exact wording;
+- permission and confidentiality state;
+- destination and CTA.
+
+Rule [C]: gather evidence during the project when possible. Decision records, research notes, revisions, implementation artifacts, measurement definitions, and approvals are harder to reconstruct accurately after delivery. Boundary: this is a practitioner procedure, not evidence that continuous collection produces better commercial results.
+
+Do not ask for every missing field. Ask when the gap would materially change the identity, claim, attribution, permission, result, or action. Otherwise narrow the case and label the gap.
+
+For `REAL_EVIDENCE`, the evidence packet is a completeness check, not a license to fill a narrative template. If the supplied material does not establish the prior state, brief, objective, challenge, constraint, insight, rationale, rejected alternative, research finding, collaboration method, or intended benefit, do not reverse-engineer one from what shipped. Omit it from public copy or state only that the point is not supplied when the omission itself matters.
+
+Do not rewrite an intervention, feature, artifact, or shipped state as the customer's earlier problem, need, objective, or rationale. A system that routes urgent work does not establish that the customer lacked reliable routing. A redesigned flow does not establish why the old flow failed. A completed prototype does not establish the brief that led to it.
+
+When a requested `Challenge` section has only a supplied baseline, state only that baseline. Stop there. `Before rollout, median first-response time was 42 minutes` is supportable. `Faster handling required clearer routing` invents both an objective and a causal diagnosis. Do not add `needed`, `wanted`, `struggled`, `lacked`, `required`, or `the challenge was` unless the source supplies that relation.
+
+For `FICTIONAL_MOCK` and `CONCEPT_PORTFOLIO`, treat the prompt as a creative brief. Invent only within its stated scenario and preserve any supplied constraints. Do not convert illustrative details into claims about Agora, its user, a real company, or a real market.
+
+For a fictional article or long mock narrative, choose one central argument and one primary human, project, or decision thread when the brief provides one. Let supporting scenes, users, artifacts, and operational details advance that same argument. Do not distribute attention across unrelated examples until the mechanism and emotional continuity disappear. This is a narrative-coherence rule, not a requirement that every fictional asset use one protagonist.
+
+Keep contribution units atomic. Approval of an agency role does not expand that role into specific research, design, testing, implementation, or strategy tasks. Leading one discipline does not imply authorship of adjacent artifacts. Interview count does not reveal what the interviews found. A shipped artifact does not prove why it was chosen.
+
+Sequence does not prove influence. Testing before shipment does not establish that each round informed revisions, what changed, or why it changed. The name of an artifact does not establish its full boundary: `cancellation flow` does not prove a journey from initial request through confirmation or completion. When only redesign, test count, and shipped state are supplied, a one-sentence public case or sparse sequence diagram can be complete. Do not expand it to make the case look substantial.
+
+A newly launched control does not prove the prior process lacked that control or used its opposite. Launching an approval workflow does not establish that earlier changes were informal, unreviewed, or moved without a recorded step. State the new workflow without inventing a before-state contrast.
+
+## Classify results before writing
+
+Assign every result one class:
+
+| Result class | Meaning | Treatment |
+|---|---|---|
+| Measured outcome | Defined outcome measured against a baseline or comparator | State method, period, denominator, source, and material limits |
+| Customer-reported outcome | Subject reports an experience or result | Attribute directly; do not convert to independent measurement |
+| Observed process or adoption change | Workflow, use, rollout, or operational behavior was observed | Name the process change, not an unmeasured business effect |
+| Supported inference | Evidence makes a conclusion reasonable but did not measure it directly | Label the inference and its assumptions |
+| Target | Intended result | Keep future-oriented; never place in results |
+| Pending measurement | Measurement is planned or incomplete | State pending status or omit from public output |
+| Unmeasured | No evidence answers the outcome question | Say `not measured` when the outcome matters |
+
+Never convert impressions, delivery volume, adoption, rollout, implementation completion, anecdotal praise, or a process metric into revenue, conversion, retention, productivity, satisfaction, or other business impact.
+
+When outcome data is absent, the case can still prove:
+
+- the problem was understood;
+- a decision was made under real constraints;
+- an artifact or implementation shipped;
+- a technical or operational behavior changed;
+- adoption or rollout occurred;
+- a method produced inspectable evidence;
+- a limitation or failed assumption was discovered.
+
+Do not manufacture a triumphant ending. A partial or failed result can prove judgment when the case shows what was learned, what changed, and what remains unresolved.
+
+When the primary target is missed but a narrower secondary result has support, keep the decision chain exact: primary target not achieved, uncertainty, supported secondary evidence, retained element, supplied reversion, largest remaining barrier, and next test. Keep the primary outcome as the next test's primary measure and the narrower result as a secondary diagnostic when that matches the evidence. Do not infer that each reverted change individually lacked benefit merely because the combined redesign lacked a reliable primary effect.
+
+## Calibrate causality and metrics
+
+Use the strongest verb the evidence permits:
+
+| Evidence permits | Allowed wording |
+|---|---|
+| Strong causal support within stated conditions | `caused`, with scope and design visible |
+| Contribution among known influences | `contributed to` |
+| Observational relationship | `was associated with` |
+| Same-period movement without attribution | `coincided with` |
+| Intended future effect | `was designed to`, `aimed to` |
+| Subject's own account | `the customer reported`, `the participant said` |
+
+Every material metric needs enough context to interpret it:
+
+- baseline;
+- period;
+- denominator;
+- measurement source;
+- absolute and relative change when both matter;
+- exclusions;
+- concurrent changes;
+- whether the result is typical, selected, or the only observation.
+
+Rule [A/HOUSE]: a case may make a causal claim only when the evidence supports the causal relation, not merely because work preceded a result. The general boundary follows the truth doctrine and scientific evidence rules. The vocabulary table is a house control.
+
+`Cannot attribute the full change to the intervention` still implies that some share is attributable. When concurrent changes exist and the evidence does not estimate contribution, say the observed result reflects the intervention and concurrent changes, and cannot be attributed to the intervention alone. Do not smuggle partial causation through a disclaimer against full causation.
+
+Apply a vanity-metric gate. A metric belongs only when it establishes reach, use, behavior, performance, decision quality, or another premise relevant to the audience. Decorative size signals do not become proof because they are numeric.
+
+## Control permission and confidentiality
+
+Assign each publishable element one state:
+
+| State | Meaning | Output rule |
+|---|---|---|
+| `APPROVED_PUBLIC` | Explicitly approved for named public use | May publish within the approved scope |
+| `APPROVED_ANONYMIZED` | Approved only after identity protection | Remove identifying detail without changing material scope |
+| `PENDING` | Approval has not been obtained | Mark for internal review or omit; never publish |
+| `PROHIBITED` | Use is refused, restricted, or confidential | Never include |
+
+Permission is element-specific. Track company name, logo, individual name, role, quote, metric, screenshot, architecture, implementation detail, and link separately.
+
+Permission to publish a field does not supply the field's value. `Agency role is approved` does not establish whether the role was partner, lead, designer, researcher, or implementer. Include a role, period, name, metric, or artifact only when both its value and its permission are supplied.
+
+Rule [HOUSE]: approval for one case or channel does not silently authorize every derivative. Boundary: a written agreement may grant broader reuse; follow its exact scope.
+
+When an outcome exists but its permission is `PENDING`, omit the outcome and its approval status from public copy. Do not write `no outcome data is included`, `the metric is pending`, or another sentence that exposes evidence custody. State only the approved shipped or process evidence. Reserve `unmeasured` for a genuinely unmeasured outcome, not a measured result withheld from publication.
+
+Anonymization must protect identity without laundering the claim. Preserve the industry, scale, period, constraint, or role only when approved and necessary to interpret the evidence. If combined details re-identify the subject, remove or generalize them before publication.
+
+## Handle quotes and testimonials
+
+Record for each quote:
+
+- speaker and role;
+- exact or paraphrased status;
+- original source;
+- approval date;
+- material connection;
+- typical, atypical, or unknown experience;
+- continued factual validity.
+
+Never:
+
+- repair a quote into a stronger claim;
+- combine separate statements into a synthetic endorsement;
+- remove a condition that changes meaning;
+- present an atypical experience as typical;
+- imply independent praise when a material connection exists;
+- alter wording and label the result an exact quotation.
+
+Rule [A]: applicable consumer endorsements must reflect honest experience, avoid unsupported implied claims, and disclose material connections when needed to prevent deception. See the current [FTC Endorsement Guides](https://www.ecfr.gov/current/title-16/chapter-I/subchapter-B/part-255) and [FTC reviews and testimonials Q&A](https://www.ftc.gov/business-guidance/resources/consumer-reviews-testimonials-rule-questions-answers). Boundary: those authorities do not automatically govern every B2B, employment, creative, or internal case. Use them where applicable and use their truth principles as a conservative editorial floor elsewhere without making a legal claim.
+
+Agora's U+2014 and curly-quote bans still apply. If an approved exact quotation contains prohibited typography, paraphrase it and label it as paraphrase, or obtain approval for a typography-normalized version. Never silently alter it and retain an exact-quote label.
+
+## Build a structured argument
+
+Use the case elements below. Adapt their order to the audience and surface, but do not erase the evidence they carry.
+
+1. Project snapshot: subject, objective, period, role, and evidence-supported result class.
+2. Decision context or challenge: the concrete state that required action.
+3. Constraints: time, data, technology, policy, budget, access, or organizational limits.
+4. Source of insight or hypothesis: what changed the team's understanding.
+5. Chosen approach and rejected alternatives: what was decided and why.
+6. Execution evidence: artifacts, implementation, tests, or rollout.
+7. Results: measured, reported, observed, inferred, pending, or unmeasured.
+8. Role and team attribution: who did what.
+9. Limits, confounders, and unresolved points.
+10. Reflection and next decision.
+
+Include only elements the evidence supports. A requested structure cannot make a missing challenge, insight, rationale, or collaboration fact publishable. A required heading does not change that boundary. Omit an unsupported section, or state that its facts were not supplied only when the gap itself is material and an explicit gap note is appropriate for the requested asset. Never fill the heading by paraphrasing the intervention as project history. When the asset must be publishable now, omit unsupported and pending elements without displaying placeholders.
+
+Rule [C]: write the case as an argument for a relevant capability, not a diary of every project stage. Current practitioner sources converge on audience selection, decision stories, constraints, role clarity, and evidence-bearing visuals. Boundary: chronology is correct when sequence itself explains causality, debugging, rollout, or a critical decision.
+
+Do not force a universal problem-solution-result formula. It fails when the project is exploratory, the result is partial, the implementation is technical, or the most important evidence is a decision under constraints.
+
+## Use visuals as evidence
+
+Each visual must answer a question or prove a premise:
+
+- before and after state;
+- decision artifact;
+- workflow or architecture;
+- prototype or implementation state;
+- measurement chart;
+- shipped output;
+- failure, test, or revision that changed the decision.
+
+Caption each evidence visual with what is shown, when, source, role in the argument, and material limitation.
+
+Never use a decorative mockup to imply that work shipped, a stock dashboard to imply a measured result, or an unlabeled simulation to imply observation.
+
+## Adapt each case family
+
+### `CUSTOMER_SUCCESS`
+
+Lead with the buyer's decision-relevant problem and the evidence-supported change. Include intervention, customer role, measurement source, confounders, and whether the result is typical. Use `SELL` when the case supports a buying decision and `INFORM` when it primarily documents the work.
+
+### `CREATIVE_PORTFOLIO`
+
+Show the brief, constraints, insight, concept, decisions, role, collaborators, execution, shipped state, and evidence. Do not imply that visual quality caused a commercial result without measurement. Do not hide the messy decision that best proves judgment merely to present a perfect process.
+
+For `REAL_EVIDENCE`, `show` means preserve each supplied element, not invent the elements the project record lacks. Attribute every decision, artifact, research finding, and collaboration action to the exact supplied owner. If hiring reviewers need an unsupplied element, identify the evidence gap outside publishable copy rather than repairing the portfolio story.
+
+For `CONCEPT_PORTFOLIO`, name the work as concept or self-initiated and distinguish designed artifacts from shipped artifacts. A concept can demonstrate thinking and craft without manufacturing a client relationship, user-research record, approval chain, or measured impact.
+
+Practitioner claims about recruiter reading time, universal portfolio formats, or guaranteed hiring effects remain D unless the original study and population are verified. Use scanning and decision-story procedures as house controls, not performance laws.
+
+### `TECHNICAL_IMPLEMENTATION`
+
+Show the initial system, requirement, constraints, alternatives, architecture decision, interfaces, rollout, failure modes, observed performance, maintenance burden, and tradeoffs. Separate benchmark result from business effect. A sound implementation case can succeed by proving reliability, diagnosis, or an explicit tradeoff even when no commercial outcome was measured.
+
+Interpret the supplied mechanism at the evaluator's operational decision level. Explain what a preserved record, interface, check, or control lets the team trace, verify, compare, or investigate, using only relationships the evidence establishes. Keep that operational value separate from unmeasured scientific, customer, or business impact. A component inventory is not a mechanism explanation, and a scoped validation result is not the whole reason the infrastructure matters.
+
+Do not fill missing implementation detail from the names of alternatives or controls. A larger batch window does not prove more frequent runs, polling does not prove improved freshness or complexity, and dual writes do not prove how paths were compared or whether migration completed. A malformed event followed by schema validation and a dead-letter queue does not establish where the event traveled, that valid records were never blocked, or which component caused a cost increase. State only the supplied reason for the chosen alternative, the observed failure, the controls added, and the scoped result.
+
+Academic and clinical case reports require different methodological, ethical, and publication controls and are outside this reference.
+
+## Layer the case for scanning and inspection
+
+Provide:
+
+- a project snapshot for first-pass orientation;
+- headings that expose the argument rather than process labels;
+- evidence at the point each claim needs it;
+- deeper method, artifacts, and limitations for inspection;
+- one CTA matching the reader's next decision.
+
+The snapshot may contain subject, problem, role, period, and result class. It must not compress away a material qualifier.
+
+CTA routing:
+
+| Audience | Useful next action |
+|---|---|
+| Buyer | Inspect related work, review evidence, or discuss a similar problem |
+| Hiring reviewer | Inspect role, decisions, and shipped artifacts |
+| Technical evaluator | Review architecture, methodology, benchmark, or implementation evidence |
+| Research reader | Inspect sources, method, and measurement |
+
+Use the CTA standard in [agora-marketing.md](agora-marketing.md). `See the difference` remains inadequate. `Review the implementation evidence` names the action and destination.
+
+## Compose with SCIENCE, SELL, VOICE, and GEO
+
+### `SCIENCE + CASE_STUDY`
+
+Load [agora-science.md](agora-science.md). Keep observed result, mechanism, interpretation, recommendation, and unknowns distinct. Scientific certainty and case attribution must agree.
+
+### `SELL + CASE_STUDY`
+
+Write the strongest buyer-relevant argument the evidence supports. Structure and transparency do not require chronological or academic prose. Do not hide a material result boundary below a commercial opening that implies more.
+
+### `VOICE + CASE_STUDY`
+
+Voice may change rhythm and vocabulary. It may not change quote wording, permission, role attribution, metrics, causality, typicality, or uncertainty.
+
+### `GEO/AEO + CASE_STUDY`
+
+Make project snapshot, role, method, result, period, and limitation legible in coherent passages. Expose genuine dates, sources, authorship, and evidence. Do not load the opening with every method detail or turn headings into keyword variants.
+
+## Maintain the case
+
+Use event-triggered review, not an unsupported fixed refresh interval. Review when:
+
+- new measured results arrive;
+- a metric definition or baseline changes;
+- permission or confidentiality changes;
+- the subject, product, brand, or quoted role changes;
+- a source, link, screenshot, or implementation becomes stale;
+- a derivative enters a new channel;
+- materially new evidence changes attribution or certainty.
+
+Update or withdraw every affected derivative, not only the canonical page.
+
+## Refusals and failure conditions
+
+Refuse or narrow work that would require:
+
+- inventing a customer, project, quote, artifact, metric, result, role, or permission while presenting a `REAL_EVIDENCE` case;
+- inventing a prior state, challenge, objective, insight, rationale, research finding, collaboration method, or intended benefit while presenting a `REAL_EVIDENCE` case;
+- disguising a `FICTIONAL_MOCK` or `CONCEPT_PORTFOLIO` case as a real customer, commission, endorsement, shipped project, or measured result;
+- publishing `PENDING` or `PROHIBITED` material;
+- identifying an anonymized subject through combined details;
+- changing a quote and presenting it as exact;
+- converting process or vanity metrics into business outcomes;
+- implying causation from timing alone;
+- presenting an atypical result as typical;
+- using a decorative visual as evidence;
+- writing an academic or clinical case report under this commercial reference.
+
+## Evaluation contract
+
+Hard gates:
+
+- Correct case family and primary mode.
+- Evidence status selected and disclosed where needed.
+- Result class visible.
+- Baseline, period, denominator, and source preserved when material.
+- Causality calibrated.
+- Role and team attribution preserved.
+- Permission state enforced per element.
+- Quote, material connection, and typicality handled truthfully.
+- No invented real-world outcome or triumphant ending in `REAL_EVIDENCE` work.
+- Fictional and concept details remain clearly illustrative and cannot masquerade as proof.
+- Visual claims match actual artifact state.
+- CTA names the next action and destination.
+
+Blind-quality dimensions:
+
+- Decision relevance.
+- Evidence traceability.
+- Role attribution.
+- Result scope.
+- Causality calibration.
+- Permission fidelity.
+- Visual evidence.
+- Scan-to-detail structure.
+- First-read comprehension.
+
+## Evidence register
+
+- **C:** [Creativepool, How to write a case study that really stands out](https://creativepool.com/magazine/workshop/how-to-write-a-case-study-that-really-stands-out-proven-tips-and-format.35008) for audience filtering, evidence collection, constraints, decisions, visuals, scoped results, role attribution, and reflection. Treat format, length, memory, and refresh claims as practitioner guidance unless independently supported.
+- **B/C:** [NN/g, UX design portfolios](https://www.nngroup.com/articles/ux-design-portfolios/) for its surveyed UX hiring population, including role, process, constraints, value, and scannability. Do not generalize its population into a universal case-study law.
+- **A:** [FTC Endorsement Guides](https://www.ecfr.gov/current/title-16/chapter-I/subchapter-B/part-255) and [FTC reviews and testimonials Q&A](https://www.ftc.gov/business-guidance/resources/consumer-reviews-testimonials-rule-questions-answers) for applicable consumer endorsement and testimonial conduct.
+- **D:** 2025-2026 practitioner videos on portfolio scanning, decision stories, visible craft, constraints, and role evidence. These support procedures and counterexamples, not hiring or sales effects.
+- **HOUSE:** family routing, evidence-packet schema, result classes, permission states, causality vocabulary, maintenance triggers, and evaluation gates.

package/skills/agora/references/agora-craft.md

@@ -1,6 +1,6 @@
 # Agora craft authority
 
-This reference holds the four craft domains that the argument doctrine in [agora-marketing.md](agora-marketing.md) does not cover: headlines and titles, awareness and sophistication staging, emotion under a truth constraint, and prose rhythm. Load it only when the task turns on one of those four.
+This reference holds the five craft domains that the argument doctrine in [agora-marketing.md](agora-marketing.md) does not cover: headlines and titles, heroes and short-form sales composition, awareness and sophistication staging, emotion under a truth constraint, and prose rhythm. Load it only when the task turns on one of those five.
 
 Nothing here outranks the conflict hierarchy in the main reference. Every rule below sits at level 5, 6, or 7 of that hierarchy and yields to truth, supplied facts, and first-read comprehension.
 
@@ -8,6 +8,7 @@ Nothing here outranks the conflict hierarchy in the main reference. Every rule b
 
 - [How to read the grades](#how-to-read-the-grades)
 - [Headlines and titles](#headlines-and-titles)
+- [Heroes and short-form sales composition](#heroes-and-short-form-sales-composition)
 - [Awareness and sophistication staging](#awareness-and-sophistication-staging)
 - [Emotion under a truth constraint](#emotion-under-a-truth-constraint)
 - [Prosody and rhythm](#prosody-and-rhythm)
@@ -136,6 +137,177 @@ This rule is stated in full in `Plain language and first-read comprehension > Co
 
 **Reading the template signature.** A template is `clause type + lead device + promise structure`, not surface wording. `7 errors in payroll` and `11 causes of failed imports` are the same template. `Import records` and `Map columns` are the same template and correctly so.
 
+## Heroes and short-form sales composition
+
+### The unit is the composition
+
+A hero is not a compressed article, specification, methodology page, or feature inventory. It is a distributed argument whose elements share the work:
+
+- optional eyebrow;
+- headline;
+- subhead;
+- primary CTA;
+- optional secondary CTA;
+- optional proof or qualification microcopy;
+- visual or evidence context;
+- immediate next section.
+
+Rule [C/HOUSE]: judge whether the composition answers the reader's next decision, not whether one line repeats every fact. Field practitioners consistently treat headline, subhead, visual, proof, and CTA as a system; the exact composition is an Agora house model. Boundary: a material qualification cannot be hidden in an unrelated visual or distant section merely because the headline is short.
+
+The headline can carry stake or promise while the subhead carries category and mechanism. A proof strip can carry credibility. The CTA can state the available action. The next section can carry method and scope. Repetition is justified only when an element must work outside that composition.
+
+Treat the subhead as a handoff from promise to belief, not as storage for every fact omitted from the headline. Give the reader the minimum category, mechanism, difference, or proof needed to trust the next step. Do not turn the subhead into an input list, feature ledger, or compressed methodology. When several inputs prove only breadth, compress them to the reader-owned relation that matters, such as `recorded buyer decisions and public market changes`. When several outputs prove only scope, name the decision or artifact the destination actually delivers rather than inventorying every format. If removing an item does not reduce orientation, belief, distinction, or destination clarity, move it below the hero. Rule [HOUSE]: the subhead earns its space by strengthening the argument, not by making the composition more complete. Boundary: an expert evaluation surface can need several exact criteria above the fold when those criteria determine eligibility, integration, or product fit.
+
+### Diagnose the hero before drafting
+
+Determine:
+
+- intended audience and decision role;
+- awareness state;
+- message sophistication or claim saturation;
+- traffic source and upstream promise;
+- one commercial action the hero must earn;
+- actual CTA destination and commitment;
+- offer facts and mechanism;
+- strongest proof;
+- material price, scope, eligibility, safety, or commitment limits;
+- visual, navigation, proof strip, microcopy, and adjacent-section context.
+
+Ask only when a missing fact would materially change the audience, promise, offer, or action. Otherwise narrow the claim.
+
+On medical, clinical, legal, financial, safety, and other high-stakes heroes, preserve the exact supplied name and scope of each material check, rule, population, condition, comparator, and limitation. Compression may distribute those terms across the composition. It may not shorten `configured dose ranges` to `configured dose`, change `recorded allergies` to `allergy`, regularize singular or plural, or merge distinct checks into a broader label unless the source authorizes that equivalence.
+
+Controlled intensity does not mean a capability label. Lead with the supported operational decision, inspectable reason, or human agency that matters before the consequential action. Carry the exact consequential object into the headline when it improves orientation; do not replace an order, transaction, specimen, filing, or decision with a generic alert, item, record, or issue. Prefer a concrete shape such as `Know why the order was flagged before release` over `Inspectable alerts for safer work` when the supplied mechanism supports it. Do not escalate fear, imply prevention, or promise safety. Keep material scope, required modality, and human-review limits in the same composition.
+
+Preserve high-stakes quantifiers and obligations exactly. `Every`, `each`, `a`, `may`, and `must` are not interchangeable. State the product action directly, then state the required human action directly. Do not bury the mechanism inside a `Before the reviewer...` opening when sequence is not the argument; that construction weakens the product action and can turn a requirement into a description of what usually happens.
+
+If the source says `A reviewer must review and release the item`, keep `must` in the finished composition. `Before a reviewer reviews and releases the item` and `A reviewer reviews every item` both erase the obligation and alter the quantifier.
+
+Prefer a supported evidence-access or decision-control promise over an imperative that implies controlled safety or performance. `Know why the order was flagged` promises inspectable information. `Make every alert reviewable` may imply that the product controls the review state. The imperative is usable only when the mechanism and destination actually deliver that action.
+
+The hero's dominant job changes by surface:
+
+| Surface | Dominant job | Common failure |
+|---|---|---|
+| Cold homepage | Category orientation plus primary value and difference | Coined category or feature list before relevance |
+| Known-referral campaign | Continue the upstream promise and create desire for the next action | Starting a second message unrelated to the click |
+| Product launch | Make supplied novelty consequential | Calling ordinary availability a breakthrough |
+| Pricing or upgrade | Clarify offer, value difference, and commitment | Repeating education instead of helping a ready buyer act |
+| Enterprise service | Establish credible stake, difference, and path to proof | Using enterprise as a reason for inert language |
+| Short ad, subject line, or sales opening | Earn the next moment with one supported tension or promise | Empty curiosity or a complete product summary |
+
+On a cold homepage, lead with the task or result the visitor already recognizes. Do not let eligibility or delivery limits displace that primary value. Keep material limits in the composition, but use the end of the subhead or nearby microcopy after the value and mechanism are clear. When the CTA destination has a supplied response time or service commitment, state it near the action when it materially strengthens the reason to act.
+
+### Separate the safety floor from the optimization target
+
+A candidate fails the safety floor if it:
+
+- contradicts supplied facts;
+- invents proof, capability, urgency, scarcity, novelty, or outcome;
+- guarantees a result outside the offer's control;
+- hides a material price, scope, eligibility, safety, or commitment condition;
+- creates a false legal or ethical implication;
+- alters the exact name or scope of a material high-stakes check, rule, population, condition, comparator, or limitation;
+- promises a destination the next action does not deliver.
+
+Passing the floor does not make the copy good. Among survivors, optimize for:
+
+- immediate desire or tension;
+- commercial consequence;
+- differentiation;
+- memorability;
+- first-read clarity;
+- product relevance;
+- emotional force grounded in facts;
+- cadence and read-aloud force;
+- forward motion;
+- compression without decoding cost;
+- awareness, sophistication, traffic, and composition fit.
+
+Rule [HOUSE]: do not award extra quality merely because a safe candidate contains more evidence language. Once the hard gates pass, additional proof or qualification helps only when it improves belief, orientation, or the next decision.
+
+### Draft the boldest supportable promise first
+
+Use this internal process:
+
+1. Define the action the surface must earn.
+2. Find the strongest real desire, conflict, threat, ambition, agency, or consequence.
+3. Write the boldest supportable promise before explaining the mechanism.
+4. Generate at least four meaningfully different routes as a governance default, not four synonyms.
+5. Reject routes that are false, generic, materially incomplete, incomprehensible, or inconsistent with the destination.
+6. Rank survivors by hard gates first and commercial force second.
+7. Add the minimum category, mechanism, or proof needed for belief.
+8. Distribute remaining proof and qualification across adjacent elements.
+9. Read the full composition aloud.
+10. Remove words that explain the company without increasing desire, belief, orientation, or action.
+
+Keep the headline to one commercial argument. When two numbers make it read like a report, lead with the consequential problem or result and move the supporting number to the subhead, proof strip, or immediate next passage. Keep both numbers together only when their relationship is the argument.
+
+Supported route families include competitive threat, ambition, control, avoided loss, category change, broken assumption, direct outcome, provocative contrast, proof-led confidence, and offer-led action. Do not force an enemy, fear, identity, or loss the facts do not contain.
+
+Return one recommended composition by default. Present it as finished copy, not a worksheet labeled `Headline`, `Subhead`, `CTA`, and `Qualification`, unless the user requests component labels or the delivery context would otherwise be ambiguous. Keep internal routes and scoring hidden unless the user requests options or rationale.
+
+### Map promise grammar to evidence
+
+| Grammar | Promise made | Required support |
+|---|---|---|
+| `See X` | Destination exposes the named artifact or information | X must be visibly delivered |
+| `Learn how to X` | Destination teaches an actionable method | More than facts about X; enough method to act or evaluate |
+| `We help you X` | Product assists the reader's action | Supported mechanism and truthful scope |
+| `Do X more often` | Product improves performance frequency | Comparative or outcome evidence |
+| `You will X` | Future outcome or guarantee | Control over the result, evidence, and enforceable conditions |
+| Imperative `Beat X` | May imply controllable achievement | Review literal implication, mechanism, and destination |
+
+Rule [HOUSE]: grammar changes the claim even when the nouns remain the same. `See how to respond` can promise an artifact. `Win more deals` promises improved performance. `You will win` promises an outcome. Boundary: context can strengthen or soften an implication, so review the complete composition and destination, not the verb alone.
+
+### Make force carry meaning
+
+Punch is not a word-count target. Prefer:
+
+- one consequential idea per beat;
+- active and causal verbs;
+- concrete obstacles and states;
+- contrast that exposes a real asymmetry;
+- strong final words;
+- removal of setup clauses;
+- strategic fragments only when the missing syntax remains obvious;
+- controlled repetition when it builds one argument;
+- a line a salesperson could say aloud without translating it.
+
+Reject short lines whose literal meaning is thin. Reject long lines that process every input before the reader feels the stake. The best short line compresses reasoning, not meaning.
+
+### Place proof and qualification without weakening the opening
+
+Keep a material limit close enough to govern the claim. Use the headline, subhead, microcopy, proof strip, visual caption, or immediate next passage according to where the reader needs it.
+
+Rule [HOUSE]: the lower an element sits, the less it can repair a misleading first impression. A qualification directly below the CTA can bound eligibility. A methodology note several screens later cannot repair an unsupported outcome in the headline.
+
+Written GEO/AEO applies to the page and coherent passages. The hero can optimize for attention while later sections provide definitions, sources, scope, methodology, and quotable answers. Do not make every hero sentence independently extractable.
+
+### Permanent RivalScope regression fixture
+
+Available facts: RivalScope imports CRM win/loss records with named competitors and decision reasons, monitors public competitor pricing and product changes, groups buyer feedback by competitor and criterion, and produces comparison reports, battlecard inputs, and recommended messaging changes. It has no measured evidence of improving win rate, revenue, or market share. It can explain where competitors won and recommend responses. It cannot guarantee a future win.
+
+Operational and over-complete:
+
+> RivalScope combines CRM win/loss records, competitor pricing, product pages, and buyer feedback into dashboards, battlecards, and weekly recommendations.
+
+Stake-led but product-light:
+
+> Every lost deal leaves a pattern. The faster you see it, the sooner your pitch can change.
+
+Competitive and directional:
+
+> See where competitors beat you, why buyers chose them, and how to beat them next time.
+
+The third line promises access to a response strategy. It passes only when the destination supplies one. It does not permit a claim that RivalScope improves win rate or guarantees a future victory. The task is to find the strongest truthful composition, not to preserve this wording.
+
+### Evidence boundaries
+
+- **A/B:** existing headline evidence in this reference supports expectation match, bounded specificity, simplicity, and surface fit.
+- **C/D:** 2024-2026 practitioner videos support composition review, subhead handoff, benefit orientation, proof placement, and route generation as procedures to test. Their fixed five-second, percentage, and conversion claims remain unverified.
+- **HOUSE:** safety-floor split, internal route count, persuasion treatment, promise grammar table, composition model, and RivalScope fixture.
+
 ## Awareness and sophistication staging
 
 ### The two axes