Skip to content

Commit 6171187

Browse files
ryderstormryderstorm
committed
docs: add context verification markers documentation
Add comprehensive documentation explaining the context verification markers feature (SDD1️⃣-SDD4️⃣) across README, website homepage, and FAQ page. Changes: - Add context verification section to README.md explaining markers and context rot - Add FAQ section in common-questions.html with detailed Q&A about emoji markers - Add brief context verification section to index.html with link to FAQ - Update wording to clarify markers are indicators, not guarantees - Fix icon styling in FAQ cards
1 parent fc8e59a commit 6171187

File tree

3 files changed

+254
-61
lines changed

3 files changed

+254
-61
lines changed

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ uvx --from git+https://github.com/liatrio-labs/slash-command-manager \
4343
- **Prompt-first workflow:** Use curated prompts to go from idea → spec → task list → implementation-ready backlog.
4444
- **Predictable delivery:** Every step emphasizes demoable slices, proof artifacts, and collaboration with junior developers in mind.
4545
- **No dependencies required:** The prompts are plain Markdown files that work with any AI assistant.
46+
- **Context verification:** Built-in emoji markers (SDD1️⃣-SDD4️⃣) detect when AI responses follow critical instructions, helping identify context rot issues early.
4647

4748
## Why Spec-Driven Development?
4849

@@ -67,6 +68,14 @@ All prompts live in `prompts/` and are designed for use inside your preferred AI
6768

6869
Each prompt writes Markdown outputs into `docs/specs/[NN]-spec-[feature-name]/` (where `[NN]` is a zero-padded 2-digit number: 01, 02, 03, etc.), giving you a lightweight backlog that is easy to review, share, and implement.
6970

71+
### Context Verification Markers
72+
73+
Each prompt includes a context verification marker (SDD1️⃣ for spec generation, SDD2️⃣ for task breakdown, SDD3️⃣ for task management, SDD4️⃣ for validation) that appears at the start of AI responses. These markers help detect **context rot**—a phenomenon where AI performance degrades as input context length increases, even when tasks remain simple.
74+
75+
**Why this matters:** Context rot doesn't announce itself with errors. It creeps in silently, causing models to lose track of critical instructions. When you see the marker at the start of each response, it's an <strong>indicator</strong> that the AI is probably following the prompt's instructions. If the marker disappears, it's an immediate signal that context instructions may have been lost.
76+
77+
**What to expect:** You'll see responses like `SDD1️⃣ I'll help you generate a specification...` or `SDD3️⃣ Let me start implementing task 1.0...`. This is normal and indicates the verification system is working. For more details, see the [research documentation](docs/emoji-context-verification-research.md).
78+
7079
## How does it work?
7180

7281
The workflow is driven by Markdown prompts that function as reusable playbooks for the AI agent. Reference the prompts directly, or install them as slash commands using the [slash-command-manager](https://github.com/liatrio-labs/slash-command-manager), to keep the AI focused on structured outcomes.

‎docs/common-questions.html‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,90 @@ <h3>The SDD Advantage</h3>
302302
</div>
303303
</div>
304304
</section>
305+
306+
<!-- Context Verification Question -->
307+
<section class="phases-detailed" id="why-do-ai-responses-start-with-emoji-markers">
308+
<div class="container">
309+
<h2>Why Do AI Responses Start with Emoji Markers (SDD1️⃣, SDD2️⃣, etc.)?</h2>
310+
<p class="section-intro">You may notice that AI responses begin with emoji markers like
311+
<code>SDD1️⃣</code>, <code>SDD2️⃣</code>, <code>SDD3️⃣</code>, or <code>SDD4️⃣</code>. This is an
312+
intentional feature designed to detect a silent failure mode called <strong>context rot</strong>.
313+
</p>
314+
315+
<div class="objection-content-grid">
316+
<div class="objection-card">
317+
<div class="objection-icon">
318+
<svg width="24" height="24" viewBox="0 0 24 24" fill="none"
319+
xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
320+
<path
321+
d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 17h-2v-2h2v2zm2.07-7.75l-.9.92C13.45 12.9 13 13.5 13 15h-2v-.5c0-1.1.45-2.1 1.17-2.83l1.24-1.26c.37-.36.59-.86.59-1.41 0-1.1-.9-2-2-2s-2 .9-2 2H8c0-2.21 1.79-4 4-4s4 1.79 4 4c0 .88-.36 1.68-.93 2.25z"
322+
fill="currentColor" />
323+
</svg>
324+
</div>
325+
<h4>What Is Context Rot?</h4>
326+
<p>Research from Chroma and Anthropic demonstrates that AI performance degrades as input context
327+
length increases, even when tasks remain simple. This degradation happens silently—the AI
328+
doesn't announce errors, but gradually loses track of critical instructions.</p>
329+
</div>
330+
331+
<div class="objection-card">
332+
<div class="objection-icon">
333+
<svg width="24" height="24" viewBox="0 0 24 24" fill="none"
334+
xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
335+
<path d="M9 12l2 2 4-4" stroke="currentColor" stroke-width="2" stroke-linecap="round"
336+
stroke-linejoin="round" />
337+
<path d="M21 12c0 4.97-4.03 9-9 9s-9-4.03-9-9 4.03-9 9-9 9 4.03 9 9z"
338+
stroke="currentColor" stroke-width="2" />
339+
</svg>
340+
</div>
341+
<h4>How Verification Markers Work</h4>
342+
<p>Each prompt instructs the AI to always begin responses with its specific marker (SDD1️⃣ for
343+
spec generation, SDD2️⃣ for task breakdown, etc.). When you see the marker, it's an
344+
<strong>indicator</strong> that critical instructions are probably being followed. If the
345+
marker disappears, it's an immediate signal that context instructions may have been lost.
346+
</p>
347+
</div>
348+
349+
<div class="objection-card">
350+
<div class="objection-icon">
351+
<svg width="24" height="24" viewBox="0 0 24 24" fill="none"
352+
xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
353+
<path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z" stroke="currentColor" stroke-width="2"
354+
stroke-linecap="round" stroke-linejoin="round" />
355+
</svg>
356+
</div>
357+
<h4>What You Should Expect</h4>
358+
<p>Normal responses will start with the marker:
359+
<code>SDD1️⃣ I'll help you generate a specification...</code> or
360+
<code>SDD3️⃣ Let me start implementing task 1.0...</code>. This is expected behavior and
361+
indicates the verification system is working correctly. The markers add minimal overhead
362+
(1-2 tokens) while providing immediate visual feedback.
363+
</p>
364+
</div>
365+
</div>
366+
367+
<div class="non-goals-box">
368+
<h3>Technical Background</h3>
369+
<div class="non-goals-content">
370+
<p>This verification technique was shared by Lada Kesseler at AI Native Dev Con Fall 2025 as a
371+
practical solution for detecting context rot in production AI workflows. The technique
372+
provides:</p>
373+
<ul class="non-goals-list">
374+
<li><strong>Immediate feedback:</strong> Visual confirmation that instructions are being
375+
followed</li>
376+
<li><strong>Low overhead:</strong> Minimal token cost (1-2 tokens per response)</li>
377+
<li><strong>Simple implementation:</strong> Easy to spot in terminal/text output</li>
378+
<li><strong>Failure detection:</strong> Absence of marker immediately signals instruction
379+
loss</li>
380+
</ul>
381+
<p style="margin-top: 1rem;">For detailed research and technical information, see the <a
382+
href="https://github.com/liatrio-labs/spec-driven-workflow/blob/main/docs/emoji-context-verification-research.md"
383+
target="_blank" rel="noopener noreferrer">context verification research
384+
documentation</a>.</p>
385+
</div>
386+
</div>
387+
</div>
388+
</section>
305389
</main>
306390

307391
<footer>

0 commit comments

Comments
 (0)