@maestroagora/agora 1.2.2 → 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.