001tmf/blatant-why/by-display

BY Display Patterns

Standard display formats for all campaign output. They use Unicode box-drawing characters and markdown that render natively in Claude Code's terminal. Never use ANSI escape codes in response text — they render as literal characters.

Every other BY skill (research, screening, scoring, campaign-manager, ...) calls into these templates when it is time to talk to the user. This file is the canonical source; the literal templates live in `references/output-format-spec.md` so other skills can copy them verbatim.

When to Use This Skill

Use this skill when you are:

• ✅ Rendering campaign status for /by:status, /by:watch, or phase transitions
• ✅ Formatting screening reports (liabilities, developability, structure scores)
• ✅ Showing ranked results for /by:results or any final campaign output
• ✅ Displaying errors or quota warnings that need user attention
• ✅ Presenting a checkpoint or safety gate that requires explicit user approval
• ✅ Streaming progress during long-running design/fold jobs
• ✅ Closing a phase — every major phase ends with a "Next Up" block

Do NOT use this skill when:

• ❌ You need to compute scores — that is by-scoring; this skill only renders them
• ❌ You need to run a screening battery — that is by-screening
• ❌ You need to decide what to do next — that is by-campaign-manager / by-design-workflow
• ❌ You need raw machine-readable JSON output for another tool — emit JSON directly, not the human-facing templates here
• ❌ You want to invent a new visual style — extend the templates here instead of forking them

Inputs

This skill is consumed by other skills. Inputs are the data objects to be rendered:

Required (one of):

• Campaign checkpoint object — { campaign_id, target, phases: [{name, status, time, details}, ...], current_phase }. Source: by-campaign-manager (campaign_state.json).
• Ranked design list — [{ design_id, composite, ipSAE, ipTM, pLDDT, liabilities, verdict }, ...]. Source: by-scoring / by-screening.
• Screening report object — { design_id, liabilities: {...}, developability: {...}, structure: {...}, verdict }. Source: by-screening.
• Progress event — { phase, status (◆/✓/✗), message, elapsed }. Source: any long-running skill.
• Error object — { title, details, suggested_next }.

Optional:

• Score scale overrides — non-default thresholds for the EXCELLENT/STRONG/... labels on score bars (see references/output-format-spec.md §Score Bars).
• Provider context — { provider, tool, protocol, scaffold, budget } shown in design-launch banners.

Outputs

Markdown strings printed to the terminal. No files written by this skill itself.

For the literal Unicode/ASCII templates, see `references/output-format-spec.md`.

Clarification Questions

⚠️ CRITICAL: ASK THIS FIRST — confirm there is something to render before invoking this skill.

1. What are you trying to render? (ASK THIS FIRST) — A campaign status, a ranked results table, a screening report, an error, or a checkpoint? Each maps to a different template. Without this, do not generate any output.
2. Which data object do you have? — Pass the campaign checkpoint, the ranked design list, or the screening report object. The skill cannot make up values; if a field is missing, leave it blank or mark — (em-dash).
3. What is the audience? — User-facing terminal output (this skill) vs. machine-readable JSON for another tool (do NOT use this skill).
4. Is this an end-of-phase rendering? — If yes, append the Next-Up block. If mid-phase, use the inline ◆/✓ progress format instead.
5. Are there units to clarify? — pLDDT is 0-100 (divide by 100 for the score bar); ipSAE and ipTM are 0-1 (use directly). RMSD is in Å, lower is better.
6. Is a safety gate involved? — If lab submission or any irreversible action is next, use the checkpoint box and require explicit user approval. Never auto-proceed past a checkpoint.
7. Provider context available? — Local GPU / HPC / Tamarind affects what shows in the design-launch banner. If unknown, fall back to "compute provider: see .by/config.json".

Standard Workflow

🚨 MANDATORY: COPY TEMPLATES FROM `references/output-format-spec.md` VERBATIM — DO NOT IMPROVISE LAYOUT 🚨

1. Identify the render type. Match the data object to one of the templates above.
2. Load the template from references/output-format-spec.md.
3. Fill the slots with values from the input object. Use — (em-dash) for missing values; never invent numbers.
4. Pick the right status symbol from the table below.
5. Render the score bars at 10-block resolution. Round the filled count to the nearest integer; for ambiguous cases below 0.9, prefer the conservative (lower) count.
6. Append the Next-Up block if this is the end of a major phase.

Anti-patterns:

• ❌ Writing ANSI escape codes (\033[...) in response text → they render literally in Claude Code chat
• ❌ Varying the banner width — always 53 ━ characters
• ❌ Using GSD ► or any prefix other than BY ►
• ❌ Reprinting the full phase table on every progress update — use inline ◆/✓ lines, print the summary table ONCE at the end
• ❌ Showing raw JSON from MCP tools — always parse and present clean summaries
• ❌ Exposing API keys, tokens, or secrets in any rendered output

Status Symbols

✓  Complete / Passed / Verified
✗  Failed / Missing / Blocked
◆  In Progress / Active
○  Pending
⚠  Warning

Use ONLY these symbols. Random emoji break skimmability.

Campaign Status Banner

Use for /by:status and phase transitions.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 BY ► CAMPAIGN: {campaign_name}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
| Phase    | Status     | Time   | Details              |
|----------|------------|--------|----------------------|
| Research | ✓ Complete | 45s    | 3 PDB, 12 prior art  |
| Plan     | ✓ Complete | 30s    | Preview tier, 10 VHH |
| Design   | ◆ Active   | 1m 15s | 5/10 designs         |
| Screen   | ○ Pending  | —      |                      |
| Rank     | ○ Pending  | —      |                      |

A drop-in CLI renderer is provided at scripts/render_campaign_status.py:

python3 scripts/render_campaign_status.py \
  --checkpoint campaigns/anti-HER2/campaign_20260520_001/campaign_state.json

Progress During Design

Use for /by:watch and mid-pipeline updates.

BY ► DESIGNING ████████░░ 80% (8/10 designs)
 
Provider: Local GPU (RTX 6000)
Tool: BoltzGen | Protocol: nanobody-anything
Scaffold: caplacizumab | Budget: 10

Progress bar: 10 blocks total. █ (U+2588) for filled, ░ (U+2591) for empty. Fill proportionally to percent complete.

Ranked Results Table

Use for /by:results and final campaign output.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 BY ► RESULTS: {campaign_name} — {N} candidates ranked
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 #  Design       Composite  ipSAE   ipTM   pLDDT  Liabilities   Verdict
─── ──────────── ────────── ─────── ────── ────── ───────────── ──────────
 1  design_003   0.871      0.85    0.82   91.2   0 crit        ✓ LAB-READY
 2  design_007   0.823      0.80    0.79   88.5   1 warn        ✓ LAB-READY
 3  design_001   0.756      0.72    0.75   85.1   0 crit        ◆ FOLLOW-UP
 4  design_012   0.534      0.45    0.62   78.3   2 crit        ✗ NOT VIABLE
 
## Score Context
ipSAE  0.85  ████████░░  EXCELLENT  (top 5% of approved therapeutics)
ipTM   0.82  ████████░░  STRONG     (confident interface prediction)
pLDDT  91.2  █████████░  VERY HIGH  (reliable fold prediction)
 
## Summary
✓ 2 lab-ready candidates | ◆ 1 needs follow-up | ✗ 1 not viable
 
## Next Steps
1.Submit top 2 to Adaptyv Bio ($119-215/design)
2.Run follow-up campaign with increased budget for design_001
3.Consider alternative epitope for design_012

Screening Battery Display

Use for /by:screen and per-design screening reports.

BY ► SCREENING {design_id}
 
Liabilities:
  ✓ Deamidation     0 sites
  ✓ Isomerization   0 sites
  ✓ Oxidation       0 sites (no exposed Met)
  ✓ Free Cys        0 unpaired
  ✓ Glycosylation   0 NXS/T motifs
 
Developability:
  Charge pH 7.4    +2.1   ✓ normal range
  Hydrophobic      34%    ✓ below 45% threshold
  CDR3 length      12 aa  ✓ within range
 
Structure:
  ipSAE   0.85   ████████░░   EXCELLENT
  ipTM    0.82   ████████░░   STRONG
  pLDDT   91.2   █████████░   VERY HIGH
  RMSD    1.2A   ██░░░░░░░░   GOOD
 
VERDICT: ✓ PASS — composite score 0.871

Score Bar Format

For any metric on a 0-1 scale (or 0-100 normalized to 0-1):

{metric}  {value}  {bar}  {label}

Where bar = 10 blocks, filled proportionally: ████████░░ for 0.80.

Scale: each █ represents 10%. Round to nearest block. Examples:

• 0.85 = ████████░░ (8.5 rounds to 9, but display 8 for conservatism below 0.9)
• 0.92 = █████████░
• 0.50 = █████░░░░░
• 0.12 = █░░░░░░░░░

For pLDDT (0-100 scale), divide by 100 first: pLDDT 91.2 = 0.912 = █████████░.

Canonical thresholds and labels for ipSAE / ipTM / pLDDT / RMSD live in `references/output-format-spec.md` §Score Bars.

Error Display

Use for warnings, quota exhaustion, and failures.

╔══════════════════════════════════════════════════════╗
║  ⚠ {Error title}                                     ║
╠══════════════════════════════════════════════════════╣
║                                                      ║
║  {Details and alternatives}                          ║
║                                                      ║
╚══════════════════════════════════════════════════════╝

Checkpoint / Safety Gate

Use for lab submission gates and user approval points.

╔══════════════════════════════════════════════════════╗
║  CHECKPOINT: {Type}                                  ║
╚══════════════════════════════════════════════════════╝
 
{Content — candidates table, cost estimate, safety gate status}
 
──────────────────────────────────────────────────────
→ {ACTION PROMPT}
──────────────────────────────────────────────────────

Next Up Block

Always show at the end of major phase completions.

──────────────────────────────────────────────────────
 
## ▶ Next Up
 
**{Action}** — {description}
 
`/by:{command}`
 
<sub>`/clear` first → fresh context window</sub>
 
──────────────────────────────────────────────────────

Long-Running Job Display

Use for SSH remote jobs, HPC dispatch, and Tamarind cloud jobs that take minutes to hours.

Fire-and-Forget Pattern

For jobs submitted to remote compute:

BY ► JOB SUBMITTED