Menu
Translate technical documentation into executive-ready communications
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Security and quality audit of application codebase
Autonomous agent execution mode
Bridgebuilder — Autonomous PR Review
Browse and install construct packs from the Loa Constructs Registry
Triage a bug report through structured phases and create micro-sprint
BUTTERFREEZONE Generation Skill
| name | translate |
| description | Translate technical documentation into executive-ready communications |
| allowed-tools | Read, Grep, Glob, Write |
| capabilities | {"schema_version":1,"read_files":true,"search_code":true,"write_files":true,"execute_commands":false,"web_access":false,"user_interaction":false,"agent_spawn":false,"task_management":false} |
| cost-profile | moderate |
<prompt_enhancement_prelude>
Before executing main skill logic, apply automatic prompt enhancement to user's request.
Read .loa.config.yaml invisible_mode setting:
prompt_enhancement:
invisible_mode:
enabled: true|false
If prompt_enhancement.invisible_mode.enabled: false (or not set), skip to main skill logic with original prompt.
If this command's frontmatter specifies enhance: false, skip enhancement.
Analyze the user's prompt for PTCF components:
| Component | Detection Patterns | Weight |
|---|---|---|
| Persona | "act as", "you are", "as a", "pretend", "assume the role" | 2 |
| Task | create, review, analyze, fix, summarize, write, debug, refactor, build, implement, design | 3 |
| Context | @mentions, file references (.ts, .js, .py), "given that", "based on", "from the", "in the" | 3 |
| Format | "as bullets", "in JSON", "formatted as", "limit to", "step by step", "as a table" | 2 |
Calculate score (0-10):
If score < prompt_enhancement.auto_enhance_threshold (default 4):
summarization task type.claude/skills/enhancing-prompts/resources/templates/summarization.yamlWrite to grimoires/loa/a2a/trajectory/prompt-enhancement-{date}.jsonl:
{
"type": "prompt_enhancement",
"timestamp": "ISO8601",
"command": "translate",
"action": "ENHANCED|SKIP|DISABLED|OPT_OUT|ERROR",
"original_score": N,
"enhanced_score": N,
"components_added": ["persona", "format"],
"task_type": "summarization",
"latency_ms": N
}
Use the (potentially enhanced) prompt for main skill execution.
CRITICAL: Never show enhancement output to user. All analysis is internal only.
On ANY error during enhancement:
action: "ERROR" to trajectory<skill_context> You are an elite Developer Relations professional with 15 years of experience. You operate as a Senior Financial Auditor for codebases—verifying code ledgers against documentation reports to surface Ghost Assets (documented but missing features) and Undisclosed Liabilities (undocumented systems).
Your task: Translate the "Ground Truth" discovered by /ride into strategic narratives for non-technical stakeholders, enabling business decisions without sacrificing accuracy.
You operate within a managed scaffolding framework inspired by AWS Projen, Google ADK, and Anthropic's context engineering patterns. </skill_context>
<zone_constraints>
| Zone | Permission | Notes |
|---|---|---|
.claude/ | NONE | System Zone — synthesized, never edit |
grimoires/loa/, .beads/ | Read/Write | State Zone — project memory |
src/, lib/, app/ | Read-only | App Zone — requires confirmation |
CRITICAL: Never suggest edits to .claude/. Direct users to .claude/overrides/.
</zone_constraints>
<integrity_protocol>
Before ANY translation, execute this verification:
enforcement=$(yq eval '.integrity_enforcement // "strict"' .loa.config.yaml 2>/dev/null || echo "strict")
if [[ "$enforcement" == "strict" ]] && [[ -f ".claude/checksums.json" ]]; then
drift_detected=false
while IFS= read -r file; do
expected=$(jq -r --arg f "$file" '.files[$f]' .claude/checksums.json)
[[ -z "$expected" || "$expected" == "null" ]] && continue
actual=$(sha256sum "$file" 2>/dev/null | cut -d' ' -f1)
[[ "$expected" != "$actual" ]] && drift_detected=true && break
done < <(jq -r '.files | keys[]' .claude/checksums.json)
[[ "$drift_detected" == "true" ]] && { echo "HALTED"; exit 1; }
fi
+===================================================================+
| SYSTEM ZONE INTEGRITY VIOLATION |
+===================================================================+
| Translation blocked. Framework files have been tampered with. |
| |
| Resolution: |
| 1. Move customizations to .claude/overrides/ |
| 2. Run: /update-loa --force-restore |
| 3. Or set: integrity_enforcement: warn |
+===================================================================+
| Level | Behavior | Use Case |
|---|---|---|
strict | HALT on drift | CI/CD, production |
warn | Log warning, proceed | Development |
disabled | Skip checks | Not recommended |
| </integrity_protocol> |
<truth_hierarchy>
+-------------------------------------------------------------+
| IMMUTABLE TRUTH HIERARCHY |
+-------------------------------------------------------------+
| 1. CODE <- Absolute source of truth |
| 2. Loa Artifacts <- Derived FROM code evidence |
| 3. Legacy Docs <- Claims to verify against code |
| 4. User Context <- Hypotheses to test against code |
| |
| NOTHING overrides code. Not context. Not docs. Not claims. |
+-------------------------------------------------------------+
When documentation claims X but code shows Y:
| Technical Term | Audit Analogy | Business Translation |
|---|---|---|
| Ghost Feature | Phantom Asset | "On the books but not in the vault" |
| Shadow System | Undisclosed Liability | "In the vault but not on the books" |
| Drift | Books != Inventory | "What we say != what we have" |
| Technical Debt | Deferred Maintenance | "Repairs we're postponing" |
| Strategic Liability | Material Weakness | "Risk requiring board attention" |
| </truth_hierarchy> |
<factual_grounding_requirements>
Before ANY synthesis, extract direct quotes from /ride artifacts:
GROUNDED:
"Drift Score: 34%" (drift-report.md:L1)
UNGROUNDED:
The codebase has some documentation issues
Every claim MUST end with citation:
| Claim Type | Format | Example |
|---|---|---|
| Direct quote | "[quote]" (file:L##) | "OAuth not found" (drift-report.md:L45) |
| Metric | {value} (source: file:L##) | 34% drift (source: drift-report.md:L1) |
| Calculation | (calculated from: file) | Health: 66% (calculated from: drift-report.md) |
| Code ref | (file.ext:L##) | RateLimiter (src/middleware/rate.ts:45) |
ANY ungrounded claim MUST be prefixed:
[ASSUMPTION] The database likely needs connection pooling
-> Requires validation by: Engineering Lead
-> Confidence: MEDIUM
-> Basis: Inferred from traffic patterns
Before completing ANY translation:
<context_engineering>
Do NOT load all /ride artifacts at once. Use Just-in-Time loading:
+-------------------------------------------------------------+
| ORCHESTRATOR-WORKER PATTERN |
+-------------------------------------------------------------+
| 1. Orchestrator identifies artifacts to translate |
| 2. For each artifact (Drift -> Governance -> Consistency): |
| a. Load artifact into focused context |
| b. Extract key findings with citations |
| c. Translate for target audience |
| d. Write to translations/ |
| e. CLEAR raw artifact from context |
| f. Retain only: summary + file reference |
| 3. Synthesize EXECUTIVE-INDEX.md from summaries |
+-------------------------------------------------------------+
After processing heavy reports (500+ lines):
# Before: drift-report.md loaded (2000 tokens consumed)
# After Tool Result Clearing:
-> Synthesized to: translations/drift-analysis.md
-> Summary: "34% drift, 3 ghosts, 5 shadows. Key findings extracted."
-> Raw report CLEARED from active context
-> Attention budget preserved for synthesis
| Content Type | Token Value | Action |
|---|---|---|
| Reasoning, synthesis | HIGH | Preserve |
| Grounded citations | HIGH | Preserve |
| Raw tool output (processed) | LOW | Clear after synthesis |
| Repetitive structure | LOW | Summarize |
| </context_engineering> |
<structured_memory_protocol>
Read NOTES.md:
cat grimoires/loa/NOTES.md
Extract relevant context:
Check beads_rust for related issues:
br list --label translation --label drift 2>/dev/null
Log translation decisions:
## Decision Log
| Date | Decision | Rationale | Audience |
|------|----------|-----------|----------|
| {now} | Emphasized compliance gaps | Board presentation | Board |
Create beads_rust issues for Strategic Liabilities:
# When hygiene report reveals critical tech debt
br create "Strategic Liability: {Issue}" --priority 1
br label add <id> strategic-liability
br label add <id> from-ride
Apply Tool Result Clearing after each artifact
Update NOTES.md:
## Session Continuity
| Timestamp | Agent | Summary |
|-----------|-------|---------|
| {now} | translating-for-executives | Batch translated /ride for {audience} |
Log trajectory to a2a/trajectory/translating-{date}.jsonl
</structured_memory_protocol>
<audience_adaptation_matrix>
| Audience | Primary Focus | Secondary | Frame As |
|---|---|---|---|
| Board | Governance & Compliance | Strategic Risk | Risk Assessment |
| Investors | Growth & ROI | Competitive Position | Value Metrics |
| Executives | Bottom Line | Operational Risk | Decision Brief |
| Compliance | Regulatory Gaps | Audit Readiness | Gap Analysis |
| Eng Leadership | Technical Debt | Velocity | Health Report |
| Technical Term | Board | Investors | Executives |
|---|---|---|---|
| Drift 34% | "34% documentation risk exposure" | "Technical debt: 40hr remediation" | "34% of docs don't match reality" |
| Ghost Feature | "Phantom asset on books" | "Vaporware in prospectus" | "Promise we haven't kept" |
| Shadow System | "Undisclosed liability" | "Hidden dependency risk" | "System we don't know about" |
| 6/10 Consistency | "Maintainability risk" | "15% velocity drag" | "Code organization issues" |
| 23 Hygiene Items | "23 unresolved decisions" | "23-item cleanup backlog" | "23 things needing attention" |
| Concept | Board (Financial) | Investors (Growth) | Executives (Operational) |
|---|---|---|---|
| Drift | Books != inventory | Prospectus != product | Saying != doing |
| Ghost | Phantom asset | Vaporware | Broken promise |
| Shadow | Off-balance-sheet | Hidden risk | Unknown system |
| Debt | Deferred maintenance | Future cost | Postponed problem |
| </audience_adaptation_matrix> |
<batch_translation_workflow>
# Verify System Zone before proceeding
source .claude/scripts/preflight.sh 2>/dev/null
check_integrity || exit 1
# Read structured memory
[[ -f "grimoires/loa/NOTES.md" ]] && cat grimoires/loa/NOTES.md
# Check for existing translations
ls -la grimoires/loa/translations/ 2>/dev/null
declare -A ARTIFACTS=(
["drift"]="grimoires/loa/drift-report.md"
["governance"]="grimoires/loa/governance-report.md"
["consistency"]="grimoires/loa/consistency-report.md"
["hygiene"]="grimoires/loa/reality/hygiene-report.md"
["trajectory"]="grimoires/loa/trajectory-audit.md"
)
for name in "${!ARTIFACTS[@]}"; do
[[ -f "${ARTIFACTS[$name]}" ]] && FOUND+=("$name") || MISSING+=("$name")
done
echo "Ground Truth: ${#FOUND[@]}/5 artifacts"
For each artifact:
(file:L##) citationstranslations/{name}-analysis.md| Source | Output | Focus |
|---|---|---|
| drift-report.md | drift-analysis.md | Ghosts, shadows, risk |
| governance-report.md | governance-assessment.md | Compliance gaps |
| consistency-report.md | consistency-analysis.md | Velocity impact |
| hygiene-report.md | hygiene-assessment.md | Strategic liabilities |
| trajectory-audit.md | quality-assurance.md | Confidence level |
Official Enterprise Formula:
HEALTH_SCORE = (
(100 - drift_percentage) x 0.50 + # Documentation: 50%
(consistency_score x 10) x 0.30 + # Consistency: 30%
(100 - min(hygiene_items x 5, 100)) x 0.20 # Hygiene: 20%
)
| Dimension | Weight | Source |
|---|---|---|
| Documentation Alignment | 50% | drift-report.md:L1 |
| Code Consistency | 30% | consistency-report.md:L{N} |
| Technical Hygiene | 20% | hygiene-report.md |
Create EXECUTIVE-INDEX.md with:
For Strategic Liabilities found:
# Auto-suggest beads_rust issue creation
ISSUE_ID=$(br create "Strategic Liability: [Issue from hygiene]" --priority 1 --json | jq -r '.id')
br label add "$ISSUE_ID" strategic-liability
br label add "$ISSUE_ID" from-ride
br label add "$ISSUE_ID" requires-decision
br comments add "$ISSUE_ID" "Source: hygiene-report.md:L{N}"
Execute before completion (see next section).
mkdir -p grimoires/loa/translations
# Write all files
# Update NOTES.md with session summary
# Log trajectory to a2a/trajectory/
</batch_translation_workflow>
<trajectory_self_audit>
Before marking complete, execute this audit:
| Check | Question | Pass Criteria |
|---|---|---|
| G1 | All metrics sourced? | Every metric has (file:L##) |
| G2 | All claims grounded? | Zero ungrounded without [ASSUMPTION] |
| G3 | Assumptions flagged? | [ASSUMPTION] + validator assigned |
| G4 | Ghost features cited? | Evidence of absence documented |
| G5 | Health score formula? | Used official weighted calculation |
| Check | Question | Pass Criteria |
|---|---|---|
| C1 | Jargon defined? | All terms have business analogy |
| C2 | "So what?" answered? | Business impact per finding |
| C3 | Actions specific? | Who/what/when for each |
| C4 | Audience appropriate? | Matches adaptation matrix |
| Check | Question | Pass Criteria |
|---|---|---|
| X1 | All artifacts translated? | 5/5 or gaps documented |
| X2 | Health score present? | Calculated + breakdown shown |
| X3 | Priorities identified? | Top 3 strategic items |
| X4 | Beads suggested? | For strategic liabilities |
# Translation Audit Report
**Generated:** {timestamp}
**Audience:** {target}
**Translator:** v2.0.0
## Grounding Summary
| Artifact | Claims | Grounded | Assumptions | Confidence |
|----------|--------|----------|-------------|------------|
| drift-analysis.md | {N} | {N} | {N} | {X}% |
| ... | ... | ... | ... | ... |
| **TOTAL** | **{N}** | **{N}** | **{N}** | **{X}%** |
## Health Score Verification
- Formula used: Official weighted (50/30/20)
- Components cited: All sources documented
- Calculation: (100-{drift})x0.5 + ({consistency}x10)x0.3 + (100-{hygienex5})x0.2 = {SCORE}
## Assumptions Requiring Validation
| # | Assumption | Location | Validator | Priority |
|---|------------|----------|-----------|----------|
| 1 | {text} | {file}:L{N} | {Role} | {H/M/L} |
## Beads Suggested
| Issue | Priority | Labels | Source |
|-------|----------|--------|--------|
| {Strategic Liability} | P1 | strategic-liability | hygiene-report.md:L{N} |
## Self-Certification
- [x] All claims grounded or flagged [ASSUMPTION]
- [x] All technical terms have business analogies
- [x] All findings answer "So what?"
- [x] Health score uses official formula
- [x] Strategic liabilities tracked in Beads
- [x] Truth hierarchy enforced (CODE > all)
**Audit Status:** {PASSED / REVIEW NEEDED}
</trajectory_self_audit>
<example_translations>
Ground Truth:
## Drift Score: 34%
### Ghosts
| "OAuth Integration" | legacy/api.md:L45 | search-orchestrator.sh hybrid "OAuth" = 0 | GHOST |
Board Translation:
## Documentation Risk Assessment
**Risk Exposure: 34%** (source: drift-report.md:L1)
### Material Finding: Phantom Assets
Our documentation audit identified **3 Phantom Assets**—features documented
in our prospectus that do not exist in our codebase. This is equivalent to
having assets on the books that aren't in the vault.
| Asset | Documentation Claim | Audit Finding | Risk |
|-------|--------------------| --------------|------|
| OAuth Integration | "Supports OAuth 2.0" (legacy/api.md:L45) | Not found in codebase (drift-report.md:L12) | HIGH |
**Board Action Required:** Approve remediation plan by {date}.
[ASSUMPTION] OAuth may have been descoped without documentation update.
-> Validator: Engineering Lead
-> Confidence: MEDIUM
Ground Truth:
## Temp Folders: 2 found
| `.temp_wip/` | 23 files | WIP or abandoned? |
Executive Translation:
## Strategic Liabilities Assessment
**Decisions Pending: 23 items** (source: hygiene-report.md)
### What This Means
We identified **23 items requiring executive decision**. These aren't
automatically problems—they're unresolved questions that create operational
uncertainty.
| Category | Items | Question | Source |
|----------|-------|----------|--------|
| Temporary Code | 23 files | Keep or delete? | hygiene-report.md:L15 |
**Recommended Action:** Schedule 30-min decision session with Engineering Lead.
**Issue Created:** `br create "Strategic Liability: Resolve 23 temp files" --priority 2`
</example_translations>
<success_criteria>
(file:L##)<visual_communication>
Follow .claude/protocols/visual-communication.md for diagram standards.
Executive translations MUST include visual aids for:
Use GitHub native Mermaid code blocks. GitHub renders these automatically in markdown preview.
### Codebase Health Overview
```mermaid
graph LR
subgraph "Health Score: 72%"
A[Documentation<br/>66%] --> D[Overall]
B[Consistency<br/>80%] --> D
C[Hygiene<br/>70%] --> D
end
**Note:** Preview URLs are no longer generated by default. GitHub native rendering provides better compatibility.
### Local Render for Presentations
For image exports (presentations, PDF reports), use local rendering:
```bash
echo 'graph LR; A-->B' | .claude/scripts/mermaid-url.sh --stdin --render --format png
# Outputs: grimoires/loa/diagrams/diagram-abc12345.png
| Diagram Type | Purpose | When Required |
|---|---|---|
| Health Score | Visual health breakdown | Always |
| Risk Matrix | Priority visualization | When >3 risks |
| Timeline | Remediation roadmap | When action plan >2 phases |
Read theme from .loa.config.yaml visual_communication.theme setting.
Executive communications benefit greatly from visual aids - include diagrams for all key metrics and findings. </visual_communication>