feat(prompts): add context verification markers to SDD workflow prompts

[ryderstorm]

Why?

This PR addresses the silent failure mode known as context rot - a phenomenon where AI performance degrades as input context length increases, even when tasks remain simple. Research from Chroma and Anthropic demonstrates that even with long context windows (128K+ tokens), models can lose track of critical instructions without signaling errors.

Evidence:

• Commit 6901e14 adds emoji-based verification markers to all SDD workflow prompts
• Research documentation added in docs/emoji-context-verification-research.md cites Chroma and Anthropic studies on context rot

The emoji verification technique, shared by Lada Kesseler at AI Native Dev Con Fall 2025, provides immediate visual feedback when critical instructions are being followed versus falling off due to context rot or inefficient compaction. This is essential for production AI workflows where silent instruction loss can cause significant issues.

What Changed?

Added context verification markers to all four SDD workflow prompts and comprehensive research documentation explaining the technique.

Key Changes:

• Added SDD1️⃣ marker to generate-spec.md prompt
• Added SDD2️⃣ marker to generate-task-list-from-spec.md prompt
• Added SDD3️⃣ marker to manage-tasks.md prompt
• Added SDD4️⃣ marker to validate-spec-implementation.md prompt
• Added research documentation at docs/emoji-context-verification-research.md explaining context rot and the verification technique

Files Modified:

• prompts/generate-spec.md
• prompts/generate-task-list-from-spec.md
• prompts/manage-tasks.md
• prompts/validate-spec-implementation.md
• docs/emoji-context-verification-research.md (new file)

Additional Notes

Context Rot Background

Context rot is the systematic degradation of AI performance as input context length increases, even when tasks remain simple. Key characteristics:

• Silent Failure: Context rot doesn't announce itself with errors - it creeps in silently
• Universal Problem: Affects even models with very long context windows (128K+ tokens)
• Detection Challenge: Models may appear fluent while losing track of critical instructions

Research from Chroma demonstrates that performance degrades as context length increases, and Anthropic found that models struggle with "needle-in-a-haystack" tasks as context grows, even when the information is present.

Verification Technique

The emoji/character verification technique works by:

1. Instruction Embedding: Critical instructions include a specific emoji/character sequence requirement
2. Response Pattern: AI is instructed to always begin responses with the marker
3. Visual Detection: Missing marker = immediate signal that context instructions weren't processed
4. Context Wall Detection: When the marker disappears, it indicates the context window limit has been reached

Why It Works:

• Token efficiency: Emojis are single tokens, adding minimal overhead
• Visual distinctiveness: Easy to spot in terminal/text output
• Pattern recognition: Models reliably follow explicit formatting instructions when they can see them
• Failure detection: Absence of marker immediately signals instruction loss

Design Decision: No Concatenation Instructions

Rationale for excluding concatenation rules:

Each SDD workflow prompt is step-specific and used independently. The prompts are designed to be self-contained for their specific workflow step:

• generate-spec.md → Only uses SDD1️⃣
• generate-task-list-from-spec.md → Only uses SDD2️⃣
• manage-tasks.md → Only uses SDD3️⃣
• validate-spec-implementation.md → Only uses SDD4️⃣

Why concatenation examples were removed:

1. Ambiguity: Showing examples like SDD1️⃣ SDD2️⃣ SDD3️⃣ SDD4️⃣ could confuse the AI into thinking it should output all markers, even when only one step is active
2. Unclear Trigger: The phrase "when multiple workflow steps are active" doesn't clearly define when concatenation would apply in practice
3. Simplicity: Each prompt should have a single, clear instruction: use YOUR marker. Simpler instructions are more reliable
4. Self-Contained Design: Each prompt is designed to work independently, so concatenation isn't needed

If concatenation becomes necessary in the future (e.g., for a unified prompt spanning multiple steps), it can be added back with clearer, more specific guidance.

Reliability Assessment

• High Reliability: When marker appears consistently, instructions are likely being processed
• Medium Reliability: When marker is inconsistent, may indicate partial context loss
• Low Reliability: When marker disappears, strong indicator of context rot or instruction loss

Note: Presence of marker doesn't guarantee all instructions were followed correctly, but absence is a clear signal of instruction loss.

• Breaking Changes: None
• Performance Implications: Minimal overhead (~1-2 tokens per response)
• Security Considerations: None - markers are visual verification only
• Testing Strategy: Manual verification that markers appear in AI responses
• Dependencies: None added
• Configuration Changes: None required
• Known Limitations: Marker presence doesn't guarantee all instructions were followed, but absence indicates instruction loss
• Related Issues: N/A

Review Checklist

• Code follows project style guidelines
• Self-review completed
• Tests added/updated for new functionality (N/A - prompt changes)
• Documentation updated (research doc added)
• No breaking changes
• Performance impact considered (minimal - 1-2 tokens)
• Security implications reviewed (none)
• Dependencies reviewed and approved (none added)

Summary by CodeRabbit

• Documentation

  • Added a new research document on emoji/character context verification and updated README, site docs, and FAQ with explanatory sections and guidance (one FAQ insertion duplicated).

• Chores

  • Updated multiple prompt-management guides to require replies to begin with explicit context-verification markers (SDD1️⃣–SDD4️⃣).

[coderabbitai]

Walkthrough

Adds documentation and site content describing an emoji-based context verification technique and inserts new "Context Verification Marker" sections into four prompt files, requiring replies to begin with sequential markers SDD1️⃣–SDD4️⃣. No public API or code logic changes.

Changes

Cohort / File(s)	Change Summary
Research documentation docs/emoji-context-verification-research.md	New research doc describing an emoji/character context verification method: origin, mechanism, implementation example, reliability/limitations, best practices, multi-step workflow integration, related techniques, sources, and recommendation.
Prompt context verification markers prompts/generate-spec.md, prompts/generate-task-list-from-spec.md, prompts/manage-tasks.md, prompts/validate-spec-implementation.md	Each prompt file gained a "Context Verification Marker" section instructing replies to ALWAYS begin with a specific sequential marker (SDD1️⃣, SDD2️⃣, SDD3️⃣, SDD4️⃣) as a mandatory reply prefix.
Docs/site content updates README.md, docs/common-questions.html, docs/index.html	Added explanatory content about the verification markers (SDD1️⃣–SDD4️⃣) across README and site pages; one insertion was duplicated in docs/common-questions.html. Formatting/text wrapping adjustments applied in docs/index.html.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Author as Prompt / Doc Author
    participant User as User
    participant Assistant as Assistant

    rect rgba(120,180,240,0.08)
    note over Author,User: Prompts/docs include Context Verification Marker (SDDx)
    Author->>User: Publish spec/prompt with required prefix SDDx
    end

    User->>Assistant: Send request referencing spec
    alt Assistant includes required marker
        Assistant->>Assistant: Prepend marker SDDx
        Assistant->>User: Response starts with SDDx + body
    else Marker omitted / verification fails
        Assistant->>User: Response without SDDx or a verification-failure note
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Check the four prompt files for correct, sequential SDD markers and consistent wording/placement.
• Review the new research doc for clarity and any accidental sensitive content.
• Inspect docs/common-questions.html for the duplicated insertion and remove duplication if unintended.

Possibly related PRs

• refactor(workflow): comprehensive spec-driven workflow prompt refactoring #26 — Refactors the same prompt files (prompts/generate-spec.md, prompts/generate-task-list-from-spec.md, prompts/manage-tasks.md, prompts/validate-spec-implementation.md); closely related at the prompt/content level.

Suggested reviewers

• RobertKelly

Poem

🐰 I nibble tokens in the glen,
I line up markers one by ten,
SDDs at every start,
Keep the context in my heart,
Hop, verify, and then — again.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately and concisely describes the main change: adding context verification markers to SDD workflow prompts.
Description check	✅ Passed	The description comprehensively addresses all template sections with detailed motivation, complete change documentation, and thorough additional notes including design rationale and reliability assessment.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/context-rot-markers

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between afba4d7 and 3f03859.

📒 Files selected for processing (3)

• README.md (2 hunks)
• docs/common-questions.html (1 hunks)
• docs/index.html (14 hunks)

🔇 Additional comments (7)

README.md (1)

46-46: Context verification marker explanation is clear and user-friendly. ✓

The additions align well with the PR objectives. Line 46 surfaces the feature in the highlights, and the new subsection (lines 71–78) explains what markers are, why they matter for detecting context rot, and what users should expect to see. The example responses at line 77 and link to research documentation provide appropriate guidance.

Also applies to: 71-78

docs/common-questions.html (3)

306-313: Section heading and intro clearly establish the context verification topic. ✓

The new section title and opening explanation introduce the emoji markers and "context rot" concept appropriately for a FAQ page.

---

315-365: Three objection cards effectively address key user questions about markers. ✓

The card structure mirrors the document's existing pattern and covers essential concerns:

• Card 1 explains what context rot is and cites research
• Card 2 clarifies how the markers detect instruction loss
• Card 3 provides concrete usage examples

The language is accessible and directly addresses the "why" behind the feature.

---

381-384: No issues found. The research documentation file exists at docs/emoji-context-verification-research.md, contains meaningful content (147 lines, 8601 bytes), and is properly structured as a markdown research report on "Emoji/Character Context Verification Technique." The link is valid and accessible.

docs/index.html (3)

237-237: Added context verification marker bullet to benefits list. ✓

Line 237 appropriately includes marker-based verification detection in the "Why This Works" section. The phrasing is concise and aligns with README.md language.

---

254-257: Marker and context-rot terminology align across files. ✓

The explanation here matches README.md and common-questions.html, maintaining consistent messaging about what markers are (SDD1️⃣–SDD4️⃣), what they detect (context rot), and their purpose (failure-detection signal).

---

251-261: Anchor link verified as valid. ✓

The anchor target #why-do-ai-responses-start-with-emoji-markers exists in docs/common-questions.html at line 307 with the matching id attribute. The section is properly structured and the link will function correctly.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}