-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
816 lines (714 loc) · 33.6 KB
/
Copy pathindex.html
File metadata and controls
816 lines (714 loc) · 33.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>The SPEC Workflow — Instruction Guide</title>
<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@500;600;700&family=Inter:wght@300;400;500;600&display=swap" rel="stylesheet">
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
html, body {
width: 100%;
height: 100%;
}
body {
background: #F4F1EA;
font-family: 'Inter', sans-serif;
color: #1B3A52;
}
/* PAGE STRUCTURE */
.page {
width: 100%;
min-height: 100vh;
padding: 60px;
display: grid;
grid-template-columns: 1fr 1fr;
gap: 80px;
align-items: flex-start;
background: #F4F1EA;
padding-bottom: 200px;
}
/* LEFT COLUMN — TEXT */
.left-column {
max-width: 520px;
}
/* RIGHT COLUMN — VISUAL */
.right-column {
display: flex;
align-items: center;
justify-content: center;
position: relative;
}
/* TYPOGRAPHY */
.section-label {
font-size: 12px;
font-weight: 700;
font-family: 'Inter', sans-serif;
text-transform: uppercase;
letter-spacing: 2px;
color: #B85C38;
margin-bottom: 16px;
}
h1 {
font-size: 52px;
font-weight: 700;
font-family: 'Space Grotesk', sans-serif;
line-height: 1.15;
color: #1B3A52;
margin-bottom: 24px;
letter-spacing: -0.5px;
}
h2 {
font-size: 28px;
font-weight: 600;
font-family: 'Space Grotesk', sans-serif;
color: #1B3A52;
margin-bottom: 16px;
margin-top: 32px;
letter-spacing: -0.3px;
}
h2:first-of-type {
margin-top: 0;
}
p {
font-size: 15px;
line-height: 1.7;
color: rgba(27, 58, 82, 0.85);
margin-bottom: 12px;
}
.subtitle {
font-size: 16px;
line-height: 1.6;
color: rgba(27, 58, 82, 0.75);
margin-bottom: 32px;
}
/* INSTRUCTION STEPS */
.steps {
margin-top: 40px;
}
.step {
margin-bottom: 20px;
padding-left: 32px;
position: relative;
}
.step::before {
content: attr(data-step);
position: absolute;
left: 0;
top: 0;
width: 24px;
height: 24px;
background: #1B3A52;
color: #F4F1EA;
display: flex;
align-items: center;
justify-content: center;
font-size: 12px;
font-weight: 700;
font-family: 'Space Grotesk', sans-serif;
border-radius: 2px;
}
.step h3 {
font-size: 14px;
font-weight: 700;
font-family: 'Space Grotesk', sans-serif;
color: #1B3A52;
margin-bottom: 4px;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.step p {
font-size: 13px;
margin: 0;
color: rgba(27, 58, 82, 0.7);
line-height: 1.5;
}
.highlight {
color: #B85C38;
font-weight: 600;
}
/* CODE BLOCK */
.code-block {
background: rgba(27, 58, 82, 0.05);
border-left: 3px solid #B85C38;
padding: 16px;
margin-top: 24px;
font-family: 'Courier New', monospace;
font-size: 11px;
line-height: 1.6;
color: #1B3A52;
overflow-x: auto;
}
/* REFERENCE CITATION */
.citation {
background: rgba(184, 92, 56, 0.05);
border-left: 3px solid #B85C38;
padding: 12px 16px;
margin-top: 12px;
font-size: 12px;
line-height: 1.5;
color: rgba(27, 58, 82, 0.75);
font-style: italic;
}
.citation a {
color: #B85C38;
text-decoration: none;
font-weight: 600;
}
.citation a:hover {
text-decoration: underline;
}
/* RIGHT COLUMN GRAPHICS */
.visual-container {
position: relative;
width: 100%;
display: flex;
flex-direction: column;
justify-content: flex-start;
}
.workflow-diagram {
display: grid;
grid-template-rows: auto auto auto auto auto auto;
gap: 16px;
width: 100%;
}
/* STEP BOXES */
.step-visual {
background: rgba(27, 58, 82, 0.04);
border: 1px solid rgba(27, 58, 82, 0.15);
padding: 24px 20px;
border-radius: 4px;
text-align: center;
position: relative;
}
.step-visual.active {
background: rgba(184, 92, 56, 0.08);
border-color: #B85C38;
}
.step-number {
font-size: 40px;
font-weight: 700;
font-family: 'Space Grotesk', sans-serif;
color: #B85C38;
margin-bottom: 8px;
}
.step-title {
font-size: 12px;
font-weight: 700;
font-family: 'Space Grotesk', sans-serif;
text-transform: uppercase;
letter-spacing: 0.8px;
color: #1B3A52;
margin-bottom: 6px;
}
.step-desc {
font-size: 11px;
line-height: 1.5;
color: rgba(27, 58, 82, 0.75);
}
/* CONNECTOR */
.connector {
height: 12px;
display: flex;
justify-content: center;
align-items: center;
margin: -8px 0;
}
.connector::after {
content: "";
width: 2px;
height: 12px;
background: #B85C38;
}
/* BOTTOM CTA */
.cta-section {
position: relative;
margin-top: 80px;
background: linear-gradient(135deg, rgba(184, 92, 56, 0.1), rgba(184, 92, 56, 0.05));
border: 1px solid rgba(184, 92, 56, 0.2);
padding: 24px 28px;
border-radius: 4px;
display: grid;
grid-template-columns: 1fr 1fr;
gap: 40px;
}
.cta-item h4 {
font-size: 11px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 1px;
color: #B85C38;
margin-bottom: 6px;
font-family: 'Space Grotesk', sans-serif;
}
.cta-item p {
font-size: 12px;
margin: 0;
line-height: 1.5;
}
/* AUTHOR & METADATA */
.author-meta {
font-size: 12px;
color: rgba(27, 58, 82, 0.6);
margin-top: 32px;
padding-top: 16px;
border-top: 1px solid rgba(27, 58, 82, 0.1);
}
.author-meta strong {
color: #B85C38;
font-weight: 600;
}
/* EXAMPLES SECTION */
.examples-section {
margin-top: 120px;
padding: 80px 60px;
background: #fff;
border-top: 1px solid rgba(27, 58, 82, 0.1);
}
.examples-container {
max-width: 1200px;
margin: 0 auto;
}
.section-intro {
font-size: 16px;
color: rgba(27, 58, 82, 0.8);
margin-bottom: 48px;
max-width: 700px;
}
.examples-grid {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 40px;
margin-bottom: 60px;
}
.example-card {
background: #F4F1EA;
border: 1px solid rgba(27, 58, 82, 0.1);
padding: 32px;
border-radius: 4px;
}
.example-card h3 {
font-size: 18px;
font-weight: 700;
font-family: 'Space Grotesk', sans-serif;
color: #1B3A52;
margin-bottom: 12px;
}
.example-label {
font-size: 11px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 1px;
color: #B85C38;
margin-bottom: 16px;
display: inline-block;
}
.example-card p {
font-size: 14px;
line-height: 1.6;
color: rgba(27, 58, 82, 0.8);
margin-bottom: 16px;
}
.example-card .highlight-box {
background: rgba(184, 92, 56, 0.08);
border-left: 3px solid #B85C38;
padding: 12px 14px;
margin-top: 16px;
font-size: 13px;
line-height: 1.5;
color: #1B3A52;
font-weight: 500;
}
.example-before-after {
margin-top: 16px;
display: grid;
grid-template-columns: 1fr 1fr;
gap: 12px;
}
.before, .after {
padding: 12px 14px;
border-radius: 3px;
font-size: 12px;
line-height: 1.5;
}
.before {
background: rgba(139, 0, 0, 0.08);
border-left: 3px solid #8B0000;
color: #4a2626;
}
.after {
background: rgba(27, 130, 100, 0.08);
border-left: 3px solid #1b8264;
color: #1a4a3a;
}
.before strong {
color: #8B0000;
font-weight: 600;
}
.after strong {
color: #1b8264;
font-weight: 600;
}
/* LISTS FOR INTERVIEW STEP */
.step ul {
list-style: none;
}
.step ul li {
font-size: 13px;
line-height: 1.6;
color: rgba(27, 58, 82, 0.7);
margin-bottom: 8px;
}
.step ul li::before {
content: "→ ";
color: #B85C38;
font-weight: 600;
margin-right: 6px;
}
/* FEATURE HIGHLIGHT */
.feature-section {
margin-top: 100px;
padding: 60px;
background: linear-gradient(135deg, rgba(184, 92, 56, 0.1), rgba(184, 92, 56, 0.05));
border: 2px solid #B85C38;
border-radius: 4px;
}
.feature-section h2 {
color: #B85C38;
margin-top: 0;
}
.feature-grid {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 40px;
margin-top: 32px;
}
.feature-item {
background: white;
padding: 24px;
border-radius: 3px;
border-left: 4px solid #B85C38;
}
.feature-item h4 {
font-size: 14px;
font-weight: 700;
font-family: 'Space Grotesk', sans-serif;
color: #1B3A52;
margin-bottom: 8px;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.feature-item p {
font-size: 13px;
margin: 0;
line-height: 1.6;
}
/* PRINT STYLES */
@media print {
body { background: white; }
.page { height: auto; padding: 40px; gap: 60px; }
}
@media (max-width: 1400px) {
.page { gap: 60px; padding: 40px; }
h1 { font-size: 44px; }
h2 { font-size: 24px; }
}
@media (max-width: 1024px) {
.page {
grid-template-columns: 1fr;
gap: 40px;
align-items: flex-start;
padding-bottom: 100px;
}
h1 { font-size: 40px; }
.right-column { position: relative; width: 100%; }
.cta-section { grid-template-columns: 1fr; gap: 20px; }
.examples-grid { grid-template-columns: 1fr; }
.example-before-after { grid-template-columns: 1fr; }
.feature-grid { grid-template-columns: 1fr; }
}
</style>
</head>
<body>
<div class="page">
<!-- LEFT: TEXT INSTRUCTIONS -->
<div class="left-column">
<div class="section-label">Instruction Guide</div>
<h1>The SPEC Workflow</h1>
<p class="subtitle">Transform vague ideas into detailed specifications through structured dialogue with Claude Code. Powered by <span class="highlight">AskUserQuestionTool</span>.</p>
<h2>Why It Matters</h2>
<p>Building without a specification is building with hope. Assumptions stay hidden until rework reveals them. The SPEC workflow forces clarity before implementation by having Claude ask the hard questions you didn't know to ask yourself.</p>
<h2>The Process</h2>
<div class="steps">
<div class="step" data-step="1">
<h3>Create</h3>
<p>Write a minimal <span class="highlight">SPEC.md</span> file. 2–5 paragraphs only. Include: core intent, user context, rough scope, key concerns. Don't pretend completeness.</p>
</div>
<div class="step" data-step="2">
<h3>Interview via AskUserQuestionTool</h3>
<p>This is where the magic happens. Claude uses <span class="highlight">AskUserQuestionTool</span> to ask targeted, revealing questions about your spec. Not surface-level "gotchas"—questions designed to expose hidden assumptions, tradeoffs, and gaps you didn't see.</p>
<p style="font-size: 13px; color: rgba(27, 58, 82, 0.7); margin-top: 12px;">Questions like:</p>
<ul style="font-size: 12px; color: rgba(27, 58, 82, 0.7); margin: 12px 0 0 0; padding-left: 20px;">
<li>"When you say 'real-time', what's the maximum acceptable latency?"</li>
<li>"How do you handle conflicts when two users edit simultaneously?"</li>
<li>"What's your definition of 'scalable'—users, requests per second, or data volume?"</li>
<li>"If this feature fails, what's the business impact?"</li>
</ul>
<div class="code-block">
"read this @SPEC.md and interview me using AskUserQuestionTool across 2-3 rounds. Each round: ask 2-4 multi-part questions probing technical implementation, data models, failure scenarios, scale requirements, UI/UX tradeoffs, and architectural choices. Make questions non-obvious and build on previous answers. After all rounds, write the refined spec to @SPEC.md with a 'Decisions Made' section."
</div>
<div class="citation">
<strong>The Key:</strong> AskUserQuestionTool forces you to articulate what you actually mean. "Collaborative" becomes explicit. "Fast" gets measured. "Scalable" gets defined. This dialogue is where vague intentions crystallize into specifications. The tool presents 2-4 options per question, creating structured decision points rather than free-form dialogue. Inspired by <a href="https://x.com/trq212/status/2005315275026260309?s=20" target="_blank">@trq212's insights on spec-driven development</a>.
</div>
</div>
<div class="step" data-step="3">
<h3>Finalize & Implement</h3>
<p>Claude writes the <span class="highlight">detailed specification</span> to SPEC.md with explicit decisions, tradeoffs, and architecture. Then: start a fresh Claude Code session with this refined spec to implement. The separation prevents context contamination and gives Claude focused scope for clean code.</p>
</div>
</div>
<h2 style="margin-top: 40px;">The Outcome</h2>
<p><span class="highlight">Precision in intent</span> precedes elegance in implementation. The specification isn't a constraint—it's a blueprint for inevitability.</p>
<div class="author-meta">
<strong>By <a href="https://w230.net" style="color: #B85C38; text-decoration: none;">Simone Leonelli</a></strong> • December 2025
</div>
</div>
<!-- RIGHT: VISUAL WORKFLOW -->
<div class="right-column">
<div class="visual-container">
<div class="workflow-diagram">
<!-- STEP 1 -->
<div class="step-visual active">
<div class="step-number">1</div>
<div class="step-title">Create SPEC.md</div>
<div class="step-desc">Write minimal rough draft<br>• Core intent<br>• User context<br>• Rough scope<br>• Key concerns</div>
</div>
<!-- CONNECTOR -->
<div class="connector"></div>
<!-- STEP 2 -->
<div class="step-visual">
<div class="step-number">2</div>
<div class="step-title">Interview with Claude</div>
<div class="step-desc">Paste prompt, Claude asks<br>• Reads your spec<br>• Finds gaps<br>• Questions assumptions<br>• You answer</div>
</div>
<!-- CONNECTOR -->
<div class="connector"></div>
<!-- STEP 3 -->
<div class="step-visual">
<div class="step-number">3</div>
<div class="step-title">Finalized Spec</div>
<div class="step-desc">Architecture emerges<br>• Detailed specification<br>• All assumptions explicit<br>• Ready for implementation</div>
</div>
</div>
</div>
</div>
</div>
<!-- CTA FOOTER -->
<div class="cta-section">
<div class="cta-item">
<h4>Time Investment</h4>
<p>~30 minutes of interview dialogue. Saves weeks of rework.</p>
</div>
<div class="cta-item">
<h4>Start Today</h4>
<p>Create SPEC.md for your next project. Let the dialogue reveal what needs to be built.</p>
</div>
</div>
<!-- THE KEY: AskUserQuestionTool FEATURE -->
<div style="padding: 0 60px;">
<div class="feature-section">
<h2>The Secret Sauce: AskUserQuestionTool</h2>
<p style="font-size: 15px; margin: 16px 0 32px 0;">This entire workflow is powered by Claude Code's AskUserQuestionTool feature. It's what transforms a vague idea into a precise specification through structured, targeted questioning.</p>
<div class="feature-grid">
<div class="feature-item">
<h4>Structured Decision Points</h4>
<p>AskUserQuestionTool presents 2-4 options per question, creating <span class="highlight">structured decision points</span> rather than open-ended dialogue. Each answer is explicit and traceable. No ambiguity. No "I think I said that" moments.</p>
</div>
<div class="feature-item">
<h4>Reveals Hidden Assumptions</h4>
<p>You think your spec is clear. It's not. The tool asks questions that expose what you didn't consciously define: latency targets, failure scenarios, edge cases, scale thresholds, and priority conflicts.</p>
</div>
<div class="feature-item">
<h4>Questions You Wouldn't Ask</h4>
<p>Claude knows which questions matter. "What happens when X fails?" "How do you define success for this feature?" "When does performance matter most?" These aren't obvious—Claude finds them based on domain patterns.</p>
</div>
<div class="feature-item">
<h4>Forces Articulation</h4>
<p>Vague thinking cannot survive structured questioning. When asked "What do you mean by 'fast'?", you're forced to say "sub-100ms response time" or "loads in under 2 seconds"—precision emerges through choice, not discussion.</p>
</div>
<div class="feature-item">
<h4>Multi-Round Interviews</h4>
<p>Effective spec interviews use 2-3 strategic rounds of questions, each building on previous answers. Early rounds explore scope and constraints. Later rounds probe edge cases and architectural implications. Each round typically asks 2-4 multi-part questions.</p>
</div>
<div class="feature-item">
<h4>Documents Every Decision</h4>
<p>The dialogue is the specification. Every question asked, every option chosen, becomes part of your final SPEC.md. The "Decisions Made" section documents architectural choices, tradeoffs accepted, and constraints acknowledged. Nothing is lost—all reasoning is captured.</p>
</div>
</div>
<div style="margin-top: 40px; padding: 24px; background: white; border-radius: 3px; border-left: 4px solid #B85C38;">
<p style="font-size: 14px; margin: 0;"><strong>Why This Matters:</strong> Without AskUserQuestionTool, specifications are just wishful thinking written down. With it, they're tested, challenged, and refined before code touches your idea. That's where the weeks of rework get prevented.</p>
</div>
</div>
</div>
<!-- EXAMPLES SECTION -->
<div class="examples-section">
<div class="examples-container">
<h2>Real-World Examples</h2>
<p class="section-intro">The SPEC workflow is most valuable for features with 2+ architectural decisions, integration points, or complex business logic. Here's how it prevents rework across different project types:</p>
<div class="examples-grid">
<!-- EXAMPLE 1 -->
<div class="example-card">
<span class="example-label">SaaS Product</span>
<h3>Building a Task Dashboard</h3>
<p>A team wanted to build a "collaborative task dashboard" but had conflicting visions about priorities, notifications, and team permissions.</p>
<div class="highlight-box">
<strong>The Problem:</strong> "Collaborative" meant different things to each stakeholder. Real-time collaboration? Comment threads? Role-based filtering?
</div>
<div class="example-before-after">
<div class="before">
<strong>Before SPEC</strong><br>3 months in, rebuilding core features due to conflicting assumptions
</div>
<div class="after">
<strong>After SPEC</strong><br>All assumptions explicit. Dev started confident with clear architecture
</div>
</div>
</div>
<!-- EXAMPLE 2 -->
<div class="example-card">
<span class="example-label">API Integration</span>
<h3>Third-party Payment Gateway</h3>
<p>Integrating Stripe seemed straightforward until questions arose: should we retry failed transactions? How do we handle disputes? What currencies?</p>
<div class="highlight-box">
<strong>The Problem:</strong> Assumed "integration" was just API calls. Ignored critical business logic around edge cases and compliance.
</div>
<div class="example-before-after">
<div class="before">
<strong>Before SPEC</strong><br>Launched without retry logic. Lost revenue from recoverable failures
</div>
<div class="after">
<strong>After SPEC</strong><br>Strategy defined for retries, edge cases, and compliance upfront
</div>
</div>
</div>
<!-- EXAMPLE 3 -->
<div class="example-card">
<span class="example-label">Mobile App</span>
<h3>Offline-First Social Feed</h3>
<p>Wanted an app that works without internet, but the specification didn't address sync conflicts, data consistency, or storage limits.</p>
<div class="highlight-box">
<strong>The Problem:</strong> "Offline-first" is an architectural choice with deep implications. Can't be decided mid-implementation.
</div>
<div class="example-before-after">
<div class="before">
<strong>Before SPEC</strong><br>Architecture pivoted halfway through after discovering sync complexity
</div>
<div class="after">
<strong>After SPEC</strong><br>Conflict resolution strategy determined before a single line of code
</div>
</div>
</div>
<!-- EXAMPLE 4 -->
<div class="example-card">
<span class="example-label">Admin Tool</span>
<h3>Data Export System</h3>
<p>Building a tool to "export user data in multiple formats" raised questions: which formats? CSV integrity? Real-time or scheduled? What about 10GB+ datasets?</p>
<div class="highlight-box">
<strong>The Problem:</strong> Scope creep disguised as a simple feature. Different stakeholders expected different capabilities.
</div>
<div class="example-before-after">
<div class="before">
<strong>Before SPEC</strong><br>Built for small datasets. Crashed with enterprise customers
</div>
<div class="after">
<strong>After SPEC</strong><br>Architecture handles scale, formats, and async processing from day one
</div>
</div>
</div>
</div>
<!-- WHAT CHANGED SECTION -->
<h2 style="margin-top: 60px;">What Changed</h2>
<p class="section-intro">Three patterns across all successful SPEC workflows:</p>
<div class="examples-grid">
<div class="example-card">
<h3 style="color: #1b8264;">1. Hidden Assumptions Surfaced</h3>
<p>Every team assumed differently about scope, priority, and edge cases. The interview forces these out early.</p>
</div>
<div class="example-card">
<h3 style="color: #1b8264;">2. Architecture Emerged First</h3>
<p>Technical choices became explicit before coding. Real-time vs. eventual consistency? Scale assumptions? Decided upfront.</p>
</div>
<div class="example-card">
<h3 style="color: #1b8264;">3. Rework Prevented</h3>
<p>The dialogue revealed conflicts that would have surfaced during code review or testing—when rework is most expensive.</p>
</div>
<div class="example-card">
<h3 style="color: #1b8264;">4. Stakeholder Alignment</h3>
<p>By the time development starts, everyone understands what's being built and why. No surprises during handoff.</p>
</div>
</div>
<!-- WHEN TO USE SPEC -->
<h2 style="margin-top: 80px;">When to Use SPEC Workflow</h2>
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 40px; margin-top: 32px;">
<div style="background: rgba(27, 130, 100, 0.08); padding: 24px; border-radius: 4px; border-left: 4px solid #1b8264;">
<h4 style="color: #1b8264; margin-top: 0; font-weight: 700;">IDEAL FOR SPEC</h4>
<ul style="font-size: 13px; line-height: 1.7; margin: 0; padding-left: 20px; color: rgba(27, 58, 82, 0.8);">
<li>Features with 2+ architectural decisions</li>
<li>Integration points (APIs, databases, external services)</li>
<li>Complex business logic or edge cases</li>
<li>Cross-team coordination needed</li>
<li>Performance or scale concerns</li>
<li>Long-term feature development (2+ weeks)</li>
</ul>
</div>
<div style="background: rgba(139, 0, 0, 0.08); padding: 24px; border-radius: 4px; border-left: 4px solid #8B0000;">
<h4 style="color: #8B0000; margin-top: 0; font-weight: 700;">LESS NECESSARY FOR</h4>
<ul style="font-size: 13px; line-height: 1.7; margin: 0; padding-left: 20px; color: rgba(27, 58, 82, 0.8);">
<li>Simple CRUD features</li>
<li>Single-component UI changes</li>
<li>Configuration or bug fixes</li>
<li>Strictly defined requirements</li>
<li>Features under 1 day to implement</li>
<li>Iterative/MVP work with known roadmap</li>
</ul>
</div>
</div>
<!-- CLOSING -->
<div style="margin-top: 80px; padding: 40px; background: linear-gradient(135deg, rgba(184, 92, 56, 0.05), rgba(184, 92, 56, 0.02)); border: 1px solid rgba(184, 92, 56, 0.15); border-radius: 4px;">
<h2 style="margin-top: 0;">The Cost of Clarity</h2>
<p style="font-size: 15px; margin-bottom: 0;">30 minutes of structured questioning on a complex feature prevents 1-3 weeks of rework. The SPEC workflow isn't about perfection—it's about making assumptions explicit so they can be questioned and resolved early, <strong>before code changes everything</strong>.</p>
<p style="font-size: 14px; color: rgba(27, 58, 82, 0.65); margin-top: 20px; margin-bottom: 0;"><strong>Start today:</strong> For your next substantial feature, write SPEC.md. Paste the interview prompt into Claude Code. Let AskUserQuestionTool guide you toward what needs to be built.</p>
</div>
</div>
</div>
<!-- REFERENCES & RESOURCES -->
<div style="padding: 80px 60px; background: rgba(27, 58, 82, 0.02); border-top: 1px solid rgba(27, 58, 82, 0.1);">
<div style="max-width: 1200px; margin: 0 auto;">
<h2>Resources & Further Reading</h2>
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 40px; margin-top: 32px;">
<div>
<h4 style="font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: 1px; color: #B85C38; margin-bottom: 16px;">On Claude Code</h4>
<ul style="list-style: none; padding: 0; margin: 0; font-size: 13px; line-height: 1.8; color: rgba(27, 58, 82, 0.8);">
<li style="margin-bottom: 12px;"><strong><a href="https://github.com/MustBeSimo/howtoClaude" style="color: #B85C38; text-decoration: none;">How to Work with Claude</a></strong> — Your foundational guide to Claude Code features, prompting techniques, and best practices</li>
<li style="margin-bottom: 12px;"><strong>AskUserQuestionTool Documentation</strong> — Learn the technical constraints and optimal patterns for structured questioning</li>
<li><strong>Claude Code System Reference</strong> — File references (@SPEC.md syntax), session management, and tool capabilities</li>
</ul>
</div>
<div>
<h4 style="font-size: 13px; font-weight: 700; text-transform: uppercase; letter-spacing: 1px; color: #B85C38; margin-bottom: 16px;">On Spec-Driven Development</h4>
<ul style="list-style: none; padding: 0; margin: 0; font-size: 13px; line-height: 1.8; color: rgba(27, 58, 82, 0.8);">
<li style="margin-bottom: 12px;"><strong>GitHub Spec Kit</strong> — Specification-driven development framework used by leading teams</li>
<li style="margin-bottom: 12px;"><strong>Anthropic Best Practices</strong> — "Plan before code" methodology and rationale</li>
<li><strong>IEEE Research</strong> — Studies show every hour on specification saves 10 hours of rework</li>
</ul>
</div>
</div>
<div style="margin-top: 48px; padding: 24px; background: white; border-radius: 4px; border-left: 4px solid #B85C38;">
<p style="font-size: 13px; color: rgba(27, 58, 82, 0.8); margin: 0;"><strong>Start here:</strong> Read <a href="https://github.com/MustBeSimo/howtoClaude" style="color: #B85C38; text-decoration: none;">How to Work with Claude</a> to understand general Claude Code capabilities. Then apply the SPEC workflow to transform those capabilities into a structured, repeatable process for building features with clarity and confidence.</p>
</div>
</div>
</div>
</body>
</html>