Skip to content

Commit 33ef175

Browse files
New1DirectionNew1Direction
committed
docs(spec): output-tab Four-Act narrative (Pillar A) design
Restructure the 28-tab output view into a Decide → Understand → Go Deeper → Act narrative. Two-tier nav, every section keeps a home, decision control to the top, lenses labeled with prereq/time/progress, legacy deep-link map. Scope-bounded (container/IA reorg, no pipeline rewrite). Part of a 3-pillar effort (A output-tab [this], B journey, 3 Knowledge Game). Includes a rendered HTML version for review.
1 parent 9e417db commit 33ef175

2 files changed

Lines changed: 406 additions & 0 deletions

File tree

‎docs/superpowers/specs/2026-06-16-output-tab-four-acts-design.html‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>Output Tab — Four-Act Narrative (Pillar A)</title>
7+
<style>
8+
:root {
9+
--ink: #0f1115;
10+
--surface: #ffffff;
11+
--paper: #f6f7f9;
12+
--grey: #6b7280;
13+
--line: #e5e7eb;
14+
--cobalt: #2563eb;
15+
--electric: #1d4ed8;
16+
--good: #15803d;
17+
--warn: #b45309;
18+
--radius: 12px;
19+
}
20+
* { box-sizing: border-box; }
21+
body {
22+
margin: 0;
23+
background: var(--paper);
24+
color: var(--ink);
25+
font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, system-ui, sans-serif;
26+
-webkit-font-smoothing: antialiased;
27+
}
28+
.wrap { max-width: 860px; margin: 0 auto; padding: 56px 24px 96px; }
29+
header.doc {
30+
border-left: 4px solid var(--cobalt);
31+
padding: 4px 0 4px 20px;
32+
margin-bottom: 36px;
33+
}
34+
header.doc h1 { font-size: 2rem; line-height: 1.15; margin: 0 0 12px; letter-spacing: -0.02em; }
35+
.meta { color: var(--grey); font-size: 0.92rem; }
36+
.meta strong { color: var(--ink); font-weight: 600; }
37+
.pillars {
38+
background: var(--surface);
39+
border: 1px solid var(--line);
40+
border-radius: var(--radius);
41+
padding: 16px 20px;
42+
margin: 18px 0 0;
43+
font-size: 0.92rem;
44+
}
45+
.pillars .p { padding: 4px 0; }
46+
.pillars .now { color: var(--electric); font-weight: 600; }
47+
h2 {
48+
font-size: 1.3rem; margin: 44px 0 14px; letter-spacing: -0.01em;
49+
padding-bottom: 8px; border-bottom: 1px solid var(--line);
50+
}
51+
h3 { font-size: 1.05rem; margin: 28px 0 10px; }
52+
p { margin: 12px 0; }
53+
ul, ol { padding-left: 22px; }
54+
li { margin: 6px 0; }
55+
code {
56+
background: var(--paper); border: 1px solid var(--line);
57+
border-radius: 5px; padding: 1px 6px; font-size: 0.86em;
58+
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
59+
}
60+
table { width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.92rem; }
61+
th, td { text-align: left; padding: 9px 12px; border-bottom: 1px solid var(--line); vertical-align: top; }
62+
th { background: var(--surface); font-weight: 600; }
63+
.act {
64+
background: var(--surface); border: 1px solid var(--line);
65+
border-radius: var(--radius); padding: 4px 22px 18px; margin: 18px 0;
66+
}
67+
.act .tag {
68+
display: inline-block; margin: 18px 0 2px; font-weight: 700;
69+
letter-spacing: 0.04em; color: var(--electric); font-size: 0.95rem;
70+
}
71+
.act .sub { color: var(--grey); font-style: italic; font-size: 0.9rem; margin: 0 0 6px; }
72+
.pill {
73+
display: inline-block; font-size: 0.74rem; font-weight: 600; padding: 2px 8px;
74+
border-radius: 999px; border: 1px solid var(--line); color: var(--grey);
75+
}
76+
.pill.def { color: var(--good); border-color: #bbf7d0; background: #f0fdf4; }
77+
.pill.dem { color: var(--warn); border-color: #fde68a; background: #fffbeb; }
78+
.note {
79+
background: var(--surface); border: 1px solid var(--line);
80+
border-left: 4px solid var(--cobalt); border-radius: 8px;
81+
padding: 12px 18px; margin: 16px 0; font-size: 0.94rem;
82+
}
83+
.ac li { margin: 8px 0; }
84+
footer { margin-top: 56px; color: var(--grey); font-size: 0.85rem; border-top: 1px solid var(--line); padding-top: 16px; }
85+
</style>
86+
</head>
87+
<body>
88+
<div class="wrap">
89+
90+
<header class="doc">
91+
<h1>Output Tab — Four-Act Narrative</h1>
92+
<div class="meta">
93+
<strong>Pillar A</strong> &middot; 2026-06-16 &middot; Status: <strong>Approved (design)</strong> — pending implementation plan<br>
94+
Surface: the extension's analysis/verdict view (<code>output-tab.html</code> + <code>output-tab.js</code>)
95+
</div>
96+
<div class="pillars">
97+
Part of a 3-pillar "simpler to use and digest" effort:
98+
<div class="p"><span class="now">Pillar A — Output-tab narrative</span> &larr; this spec, building first</div>
99+
<div class="p">Pillar B — Cross-app journey (circular nav, entry points, save/discovery clarity)</div>
100+
<div class="p">Pillar 3 — The Knowledge Game (library + corkboard + canvas: smooth, juicy, addictive — mastery + discovery + collection + crafting, to "plug pieces together and think in new ways")</div>
101+
</div>
102+
</header>
103+
104+
<h2>Problem</h2>
105+
<p>The output tab is information-rich and genuinely good — the problem is purely presentation and flow. From a current-state audit:</p>
106+
<ol>
107+
<li><strong>28 flat tabs.</strong> Verdict, ELI5, Technical, Use-Cases, Skip-If, Enables, Pros-Cons, Alternatives, Health, Red-Flags, Tech-Stack, + Deep-Dive/Systems/Ideate/Prioritize/SKTPG, + Docs/Maintenance/License/Diff/Fits-Stack, + Similar/Versus/Synergies/Connections/Combine, + Ask/Canvas. No sense of what to read first or in what order.</li>
108+
<li><strong>No narrative, weak wayfinding.</strong> The Verdict landing tries to be everything (11 stacked sections, flat hierarchy); the <strong>Decision control (Adopt/Trial/Hold/Reject) is buried ~2000px down</strong>; key info is previewed on Verdict but fully rendered elsewhere with no jump links; fit verdict, red flags, and tech stack each render in two places.</li>
109+
<li><strong>Opaque "lenses," hidden prerequisites.</strong> "Lens" is never explained; Canvas silently needs Deep Dive first; library tabs need 2+ scans; multi-stage runs give no progress/ETA.</li>
110+
</ol>
111+
112+
<h2>Goals</h2>
113+
<ul>
114+
<li>Reorganize the output tab into a <strong>four-act narrative</strong>: Decide &rarr; Understand &rarr; Go Deeper &rarr; Act.</li>
115+
<li>Add real hierarchy, wayfinding (preview &rarr; jump), and lens clarity (label + prerequisite + time estimate + live progress).</li>
116+
<li><strong>Preserve every piece of information</strong>, all functionality, all deep links, and per-repo position recall. Nothing is removed.</li>
117+
</ul>
118+
119+
<h2>Non-goals</h2>
120+
<ul>
121+
<li>No rewrite of individual section internals or the analysis pipeline (<code>background.js</code> runners, prompts, parsers stay as-is).</li>
122+
<li>No gamification / motion juice (that is Pillar 3).</li>
123+
<li>No settings redesign, no new analysis features.</li>
124+
<li><strong>One folded-in exception:</strong> the small circular library&harr;output navigation fix (central to "flow" and cheap).</li>
125+
</ul>
126+
127+
<h2>Structure: chosen approach</h2>
128+
<p><strong>Four Acts, two-tier navigation.</strong> Four primary acts as the top-level nav; each act opens its own focused, bounded view containing its grouped sections. The user always knows which act they are in; never an endless scroll. Keyboard navigation preserved. Cleanest fit for the zero-build codebase.</p>
129+
130+
<h2>The four acts — complete section mapping</h2>
131+
<p><span class="pill def">Default</span> = shown immediately after a scan. <span class="pill dem">On-demand</span> = user triggers an AI run.</p>
132+
133+
<div class="act">
134+
<span class="tag">&#9312; DECIDE</span>
135+
<p class="sub">"should I use this, and what do I do about it?" — the landing</p>
136+
<table>
137+
<tr><th>Element</th><th>When</th><th>Notes</th></tr>
138+
<tr><td>Fit verdict (level + label + why)</td><td><span class="pill def">Default</span></td><td>Anchored at top</td></tr>
139+
<tr><td>Bottom line (one-liner)</td><td><span class="pill def">Default</span></td><td></td></tr>
140+
<tr><td><strong>Decision control</strong> (Adopt/Trial/Hold/Reject + note)</td><td><span class="pill def">Default</span></td><td><strong>Moved to the top</strong> (was buried at page bottom)</td></tr>
141+
<tr><td>At-a-glance facts (health, stars/license/lang, pros/cons/flag counts)</td><td><span class="pill def">Default</span></td><td>Compact summary row</td></tr>
142+
<tr><td>Top red flags (up to 3)</td><td><span class="pill def">Default</span></td><td>Distinct "warning" treatment; link to full list</td></tr>
143+
<tr><td>Where-to-start cards</td><td><span class="pill def">Default</span></td><td>if present</td></tr>
144+
<tr><td>Since-last-scan diff callout</td><td><span class="pill def">Default</span></td><td>if prior scan</td></tr>
145+
<tr><td>"Worth noting" highlights</td><td><span class="pill def">Default</span></td><td>Now <strong>anchor</strong> to their home section (no context-thrash)</td></tr>
146+
</table>
147+
</div>
148+
149+
<div class="act">
150+
<span class="tag">&#9313; UNDERSTAND</span>
151+
<p class="sub">deep reading; all pre-computed, no waiting</p>
152+
<table>
153+
<tr><th>Element</th><th>When</th><th>Notes</th></tr>
154+
<tr><td>ELI5 (+ analogies)</td><td><span class="pill def">Default</span></td><td></td></tr>
155+
<tr><td>Technical</td><td><span class="pill def">Default</span></td><td></td></tr>
156+
<tr><td>Use Cases (4-grid)</td><td><span class="pill def">Default</span></td><td></td></tr>
157+
<tr><td>Skip If (4-grid)</td><td><span class="pill def">Default</span></td><td></td></tr>
158+
<tr><td>Enables</td><td><span class="pill def">Default</span></td><td></td></tr>
159+
<tr><td>Pros / Cons (full)</td><td><span class="pill def">Default</span></td><td>Verdict shows counts &rarr; jump here</td></tr>
160+
<tr><td>Red Flags (full list)</td><td><span class="pill def">Default</span></td><td>Decide shows top 3 &rarr; jump to the canonical full list here</td></tr>
161+
<tr><td>Alternatives</td><td><span class="pill def">Default</span></td><td></td></tr>
162+
<tr><td>Health (full: 4 signals + summary)</td><td><span class="pill def">Default</span></td><td><strong>Add metric explanations</strong></td></tr>
163+
<tr><td>Tech Stack (full: built_with + key_dependencies)</td><td><span class="pill def">Default</span></td><td>Verdict shows language chips &rarr; jump here</td></tr>
164+
</table>
165+
<p><strong>De-duplication rule:</strong> where Verdict shows a preview, the full version lives here and Verdict links to it. One source of truth per element.</p>
166+
</div>
167+
168+
<div class="act">
169+
<span class="tag">&#9314; GO DEEPER</span>
170+
<p class="sub">on-demand lenses about THIS repo; each a labeled card</p>
171+
<p>Each lens card shows: <strong>name &middot; one-line "what it does" &middot; prerequisite badge &middot; time estimate &middot; live stage progress.</strong></p>
172+
<table>
173+
<tr><th>Lens</th><th>Prerequisite</th><th>Notes</th></tr>
174+
<tr><td>Deep Dive (atoms &rarr; lineage &rarr; Feynman)</td><td>&mdash;</td><td>~90s, 3 stages with progress</td></tr>
175+
<tr><td>Canvas / Blueprint</td><td><strong>Needs Deep Dive</strong></td><td>prereq badge shown</td></tr>
176+
<tr><td>Systems / Ideate / Prioritize</td><td>&mdash;</td><td>framework chips</td></tr>
177+
<tr><td>SKTPG</td><td>&mdash;</td><td>auto-run by default (toggle)</td></tr>
178+
<tr><td>Docs Quality</td><td>&mdash;</td><td></td></tr>
179+
<tr><td>Maintenance</td><td>&mdash;</td><td>can be slow; show progress</td></tr>
180+
<tr><td>License</td><td>library context</td><td></td></tr>
181+
<tr><td>Since Last Scan</td><td>prior scan</td><td></td></tr>
182+
</table>
183+
</div>
184+
185+
<div class="act">
186+
<span class="tag">&#9315; ACT</span>
187+
<p class="sub">do something with it</p>
188+
<table>
189+
<tr><th>Element</th><th>Notes</th></tr>
190+
<tr><td>Save</td><td>clear saved-state feedback</td></tr>
191+
<tr><td>Ask this repo</td><td>requires a completed scan — state up front</td></tr>
192+
<tr><td>Share</td><td></td></tr>
193+
<tr><td><strong>Against your library:</strong> Similar &middot; Versus &middot; Synergies &middot; Connections &middot; Combine &middot; Fits-My-Stack</td><td>Honest "needs N scans" unlock states. Deeper gamified treatment is <strong>Pillar 3</strong>.</td></tr>
194+
</table>
195+
</div>
196+
197+
<h2>Navigation &amp; interaction</h2>
198+
<ul>
199+
<li><strong>Persistent header</strong> — repo name, meta pills, fit chip — always visible across acts.</li>
200+
<li><strong>Primary nav</strong> — four acts (Decide &middot; Understand &middot; Go Deeper &middot; Act). Default landing = Decide.</li>
201+
<li><strong>Secondary nav within an act</strong> — section list (Understand) or labeled cards (Go Deeper / Act).</li>
202+
<li><strong>Keyboard</strong> — <code>1</code>–<code>4</code> select acts; within-act keys for sections; preserve <code>r</code>/<code>f</code>/<code>l</code>/<code>o</code>.</li>
203+
<li><strong>Deep-linking</strong> — new hash scheme (<code>#decide</code>, <code>#understand/health</code>, <code>#deeper/deep-dive</code>, <code>#act/versus</code>) with a <strong>legacy slug map</strong> so every old <code>#slug</code> still resolves.</li>
204+
<li><strong>Per-repo recall</strong> — remember act + section (<code>repolens_tab_&lt;repoId&gt;</code>).</li>
205+
</ul>
206+
207+
<h2>Component design (isolation + testability)</h2>
208+
<p>Extract a <strong>pure act-model module</strong> (e.g. <code>output-acts.js</code>), no DOM/network, exporting: <code>ACTS</code>, <code>sectionToAct()</code>, <code>routeForHash()</code> / <code>hashForRoute()</code>, <code>LEGACY_SLUG_MAP</code> + <code>resolveLegacySlug()</code>, and <code>keyboardMap</code>. <code>output-tab.js</code> consumes it to render the act shell and route; section render functions stay as-is and mount into act containers. Routing/grouping logic becomes unit-testable independent of the DOM.</p>
209+
210+
<h2>Constraints honored</h2>
211+
<ul>
212+
<li><strong>Zero-build, zero-dep, vanilla ES modules.</strong> Reorganize <code>output-tab.html</code> + <code>output-tab.js</code>; no framework/bundler/deps.</li>
213+
<li><strong>Mono Ink</strong> brand, stop-slop/human voice, no emoji on product surfaces, motion behind <code>prefers-reduced-motion</code> (reuse <code>--dur-*</code>/<code>--ease-*</code>).</li>
214+
<li><strong>No DOM test environment</strong> — pure logic to vitest; DOM glue via <code>node --check</code> + a <code>*-demo.html</code> harness.</li>
215+
<li><strong>No <code>background.js</code> contract changes</strong> — message types unchanged; front-end reorganization only.</li>
216+
</ul>
217+
218+
<h2>Testing</h2>
219+
<ul>
220+
<li><strong>vitest (pure):</strong> act-model completeness (every slug maps to exactly one act/section), legacy-slug resolution, hash round-trip, keyboard map.</li>
221+
<li><strong><code>node --check</code></strong> on glue.</li>
222+
<li><strong>Visual:</strong> an <code>output-tab</code> demo harness; Playwright screenshots at 320 / 768 / 1024 / 1440; reduced-motion; accessibility (keyboard, focus, contrast).</li>
223+
<li>Existing suite green; <code>eslint .</code> 0 errors; HTML parse gate passes.</li>
224+
</ul>
225+
226+
<h2>Migration / rollout</h2>
227+
<ol>
228+
<li>Build the pure act-model module + act shell + routing (tested first).</li>
229+
<li>Move sections into acts group-by-group, keeping tests green.</li>
230+
<li>Add the legacy-hash redirect so existing <code>#slug</code> links resolve.</li>
231+
<li>Preserve auto-save, lens runners, and all message contracts (front-end only).</li>
232+
</ol>
233+
234+
<h2>Acceptance criteria</h2>
235+
<ul class="ac">
236+
<li>All ~28 destinations reachable, grouped into the four acts.</li>
237+
<li>Decision control in Decide, visible without scrolling.</li>
238+
<li>No element rendered twice as a source of truth — previews jump to the canonical section.</li>
239+
<li>Every lens shows what-it-does + prerequisite + time estimate + live progress.</li>
240+
<li>Old deep links resolve; keyboard nav works; per-repo recall works.</li>
241+
<li>Verdict landing scannable with clear hierarchy.</li>
242+
<li>All existing tests pass + new act-model tests; <code>eslint .</code> 0 errors; HTML gate passes.</li>
243+
</ul>
244+
245+
<div class="note">
246+
<strong>Resolved decisions:</strong> Four Acts (two-tier nav) &middot; decision control &rarr; top of Decide &middot; library-relational features &rarr; Act (gamified depth deferred to Pillar 3) &middot; circular library&harr;output nav folded into A.
247+
</div>
248+
249+
<footer>RepoLens &middot; Pillar A design spec &middot; review this, then it becomes an implementation plan.</footer>
250+
251+
</div>
252+
</body>
253+
</html>

0 commit comments

Comments
 (0)