Prioritize Dream QA Today Tip card

PRODUCT.md

@@ -14,7 +14,7 @@ The product helps a user unpack a dream through a guided, step-by-step Q&A. It a
 
 The hackathon-facing experience is English-first. A visible `English / 中文` language control keeps the Chinese experience available without making judges start from a Chinese-only first screen.
 
-Success means the user receives something more useful than a one-shot interpretation: a short summary of the dream, one clear question they were trying to answer, a non-certain explanation grounded in concrete dream details, and a tiny suggestion for today. The tip can be practical, playful, or simply caring, but it must feel connected to the dream.
+Success means the user receives something more useful than a one-shot interpretation: one clear today tip first, an optional tiny action, and then a non-certain explanation grounded in concrete dream details and the user's answer. The tip can be practical, playful, or simply caring, but it must feel connected to the dream.
 
 ## Brand Personality
 
@@ -44,6 +44,7 @@ The voice is a calm dream companion who asks good questions and takes odd detail
 8. Recommendation quality is tested with a deterministic Today Tip eval set before deployment.
 9. English mode must stay natural English, including translated or paraphrased dream anchors; mixed Chinese helper text is a regression.
 10. Tiny actions should feel like a first step the user may choose, not a hard command to solve the real-world problem immediately.
+11. The final card prioritizes the Today Tip before interpretation; interpretation is supporting reflection, not the main payoff.
 
 ## Accessibility & Inclusion
 

README.md

@@ -30,7 +30,7 @@ The public hackathon demo is English-first for international judges. A visible i
 
 ## Concept
 
-Dream QA accepts dream fragments by text, image, or voice. It turns those fragments into a shared dream intake, asks a grounded follow-up question, and returns a Today Tip card: a short non-certain interpretation, one practical or caring suggestion for today, and an optional tiny action.
+Dream QA accepts dream fragments by text, image, or voice. It turns those fragments into a shared dream intake, asks a grounded follow-up question, and returns a Today Tip card: one practical or caring suggestion first, an optional tiny action, and a short non-certain supporting reflection.
 
 This is not a therapy, diagnosis, or prophecy product.
 
@@ -48,8 +48,8 @@ This is not a therapy, diagnosis, or prophecy product.
 1. Enter a dream by text, image, voice, or a mix.
 2. State or let the app infer the main question.
 3. Answer or skip one or more follow-up questions.
-4. Review a grounded interpretation.
-5. Receive one Today Tip tied to concrete dream details.
+4. Receive one Today Tip tied to concrete dream details and the user's answer.
+5. Read the supporting reflection if the user wants more context.
 
 ## Language
 

docs/handoff.md

@@ -56,6 +56,7 @@ Final positioning:
 - English mode is not just English UI chrome; generated anchors, questions, and Today Tips should read as natural English.
 - If the model receives Chinese anchors while the selected language is English, translate or paraphrase them unless a short exact quote is intentionally preserved.
 - Tiny actions should feel like five-minute first steps. Avoid urgent command phrasing such as "address it immediately."
+- The final card should show the Today Tip before interpretation; interpretation is supporting reflection and should use the user's answer when it names a real task.
 
 ## Model Decision
 

docs/prd.md

@@ -98,11 +98,13 @@ As a user, I want a clear final result so that I leave with one small thing for
 
 Acceptance criteria:
 
-- Result includes dream summary, main question, interpretation, today tip, optional tiny action, optional caring note, and safety note when needed.
+- Result includes dream summary, main question, today tip, optional tiny action, supporting interpretation, optional caring note, and safety note when needed.
+- Result presents the Today Tip before supporting interpretation.
 - Result is readable on mobile and desktop.
 - Result avoids medical, prophetic, or deterministic framing.
 - Today tip references a concrete dream anchor.
 - Optional tiny action is a five-minute first step, not a command to solve the whole issue immediately.
+- Supporting interpretation uses the user's answer when the answer names a concrete waking-life task.
 
 #### Story 6: Bilingual Demo
 

docs/smoke/2026-06-10-tip-first-card-smoke.md

@@ -0,0 +1,88 @@
+# Dream QA Tip-First Card Smoke - 2026-06-10
+
+## Scope
+
+- Put the final Today Tip before supporting interpretation.
+- Make supporting interpretation use the user's waking-life answer when it names a concrete task.
+- Preserve English-only output quality and the existing Chinese toggle.
+
+## TDD Red
+
+Focused red commands:
+
+```text
+.venv/bin/python -m pytest tests/test_render.py tests/test_ui_actions.py tests/test_today_tip_quality_eval.py -q
+.venv/bin/python scripts/evaluate_today_tip_quality.py
+```
+
+Observed failures before implementation:
+
+```text
+test_today_tip_card_prioritizes_tip_before_interpretation
+test_english_interpretation_uses_user_answer_before_tip
+test_today_tip_quality_eval_passes_fixture_cases
+elevator_email_first_sentence: missing_interpretation_terms:overdue email
+```
+
+## Local Verification
+
+Commands:
+
+```text
+.venv/bin/python -m pytest -q
+.venv/bin/python scripts/evaluate_today_tip_quality.py
+git diff --check
+```
+
+Observed:
+
+```text
+97 passed, 2 warnings
+{"case_count": 11, "failures": {}, "passes": true}
+git diff --check clean
+```
+
+## Local Gradio Config
+
+Observed from `http://127.0.0.1:7860/config`:
+
+```text
+title=Dream QA
+version=4.44.1
+mode=blocks
+component_count=72
+```
+
+## Local Action Smoke
+
+English dream:
+
+```text
+I dreamed I was in an elevator where the floor buttons melted like wax. The number 14 kept blinking, and I felt late but strangely calm.
+```
+
+English answer:
+
+```text
+I want to make starting my overdue email easier without feeling trapped by it.
+```
+
+Observed:
+
+```text
+status=tip
+title=Today Tip
+tip_before_reflection=True
+interpretation_has_email=True
+interpretation_has_floor14=True
+has_chinese_leakage=False
+has_immediately=False
+```
+
+## Hugging Face Space Sync
+
+Pending.
+
+## Public User-View Review
+
+Pending.

docs/spec.md

@@ -176,9 +176,9 @@ The final result must include:
 
 - Dream summary.
 - Main question.
-- Grounded interpretation.
 - One primary today tip.
 - Optional tiny action.
+- Supporting grounded interpretation.
 - Optional caring note.
 - Safety note if the input indicates severe distress.
 
@@ -191,6 +191,8 @@ The final result must:
 - Use English UI/output labels by default and Chinese labels only when `中文` is selected.
 - Keep English mode fully English unless preserving a deliberate short user quote.
 - Make the optional tiny action a five-minute first step, not a demand to complete the whole waking-life problem.
+- Render the Today Tip before the interpretation so the user sees the actionable payoff first.
+- When the user answer names a real task, the supporting interpretation should bridge a dream anchor to that task.
 
 ## 10. UX Structure
 

docs/superpowers/plans/2026-06-10-dream-qa-tip-first-card.md

@@ -0,0 +1,134 @@
+# Dream QA Tip-First Card Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Put the final Today Tip before interpretation and make the interpretation paragraph use the user's waking-life answer.
+
+**Architecture:** Keep the existing `TodayTipCard` schema and Dream QA flow. Change HTML order in `render_today_tip_card`, add answer-aware interpretation polish in `pipeline.py`, and guard both with focused tests and a public Space smoke.
+
+**Tech Stack:** Python, Pydantic, Gradio, pytest, Hugging Face Space.
+
+---
+
+## File Map
+
+- Modify `dream_customs/render.py`: render the primary Today Tip before interpretation, with interpretation as a quieter details block.
+- Modify `dream_customs/pipeline.py`: when answers mention a concrete waking-life task such as email/message, make interpretation bridge the dream anchor to that answer.
+- Modify `tests/test_render.py`: assert the rendered HTML puts the primary Today Tip before the interpretation block.
+- Modify `tests/test_ui_actions.py`: assert the final card's interpretation references the user's email/message answer.
+- Modify `scripts/evaluate_today_tip_quality.py` and `tests/fixtures/today_tip_eval_cases.json`: add optional answer-term quality checks for cases where the user gives a concrete answer.
+- Modify `README.md`, `PRODUCT.md`, `docs/spec.md`, `docs/prd.md`, `docs/handoff.md`: record the tip-first output hierarchy and answer-aware interpretation rule.
+- Add `docs/smoke/2026-06-10-tip-first-card-smoke.md`: record local, HF, and browser user-view verification.
+
+---
+
+### Task 1: Tests First
+
+**Files:**
+- Modify: `tests/test_render.py`
+- Modify: `tests/test_ui_actions.py`
+- Modify: `scripts/evaluate_today_tip_quality.py`
+- Modify: `tests/fixtures/today_tip_eval_cases.json`
+
+- [x] **Step 1: Add render order test**
+
+Add a test that renders a `TodayTipCard` and asserts `Today's small suggestion` appears before `Maybe this dream is pointing to`.
+
+- [x] **Step 2: Add answer-aware interpretation test**
+
+Add a UI action test using the elevator/email flow and assert the final card text contains `overdue email` in the interpretation or copyable card text before the Tiny action.
+
+- [x] **Step 3: Add answer term eval**
+
+Extend the deterministic evaluator so a fixture may include `required_answer_terms`, and fail if those terms are missing from English output.
+
+- [x] **Step 4: Run focused red tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_render.py tests/test_ui_actions.py tests/test_today_tip_quality_eval.py -q
+.venv/bin/python scripts/evaluate_today_tip_quality.py
+```
+
+Expected before implementation: at least one focused failure for card order or answer-aware interpretation.
+
+### Task 2: Implement Tip-First Output
+
+**Files:**
+- Modify: `dream_customs/render.py`
+- Modify: `dream_customs/pipeline.py`
+
+- [x] **Step 1: Reorder result card HTML**
+
+Move the primary Today Tip article before the interpretation article. Keep Tiny action after the main suggestion.
+
+- [x] **Step 2: Quiet the interpretation block**
+
+Keep interpretation visible, but label it as supporting reflection/details rather than the first thing a user sees.
+
+- [x] **Step 3: Add answer-aware interpretation polish**
+
+When the user's answer includes email/message language, set the English interpretation to bridge the dream anchor to starting that email/message gently.
+
+- [x] **Step 4: Run focused green tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_render.py tests/test_ui_actions.py tests/test_today_tip_quality_eval.py -q
+.venv/bin/python scripts/evaluate_today_tip_quality.py
+```
+
+Expected: focused tests pass.
+
+### Task 3: Docs, Smoke, Deploy
+
+**Files:**
+- Modify: `README.md`
+- Modify: `PRODUCT.md`
+- Modify: `docs/spec.md`
+- Modify: `docs/prd.md`
+- Modify: `docs/handoff.md`
+- Add: `docs/smoke/2026-06-10-tip-first-card-smoke.md`
+- Modify: this plan file checkbox state.
+
+- [x] **Step 1: Align product docs**
+
+Record that the final screen prioritizes Today Tip first, then optional supporting interpretation.
+
+- [x] **Step 2: Run full local verification**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+.venv/bin/python scripts/evaluate_today_tip_quality.py
+git diff --check
+```
+
+Expected: all commands pass.
+
+- [x] **Step 3: Run local config/action smoke**
+
+Start the local app, check `/config`, and run the elevator/email action flow.
+
+- [ ] **Step 4: Commit and push**
+
+Commit implementation, docs, plan, and smoke evidence. Push `feature/dream-qa-tip-first-card`.
+
+- [ ] **Step 5: Merge GitHub and HF Space**
+
+Create/merge GitHub PR. Upload to HF Space with `create_pr=True`, use Chrome to click Merge, then verify public `/config`.
+
+- [ ] **Step 6: Public user-view review**
+
+Use the public Space in browser with the elevator/email dream. Confirm Today Tip appears before interpretation and interpretation references the email answer.
+
+---
+
+## Self-Review
+
+- Spec coverage: Covers the exact requested next optimization: Today Tip first, interpretation as support, interpretation tied to user answer, docs and deployment.
+- Placeholder scan: No TBD/TODO/fill-later placeholders remain.
+- Type consistency: Reuses existing `TodayTipCard`, `render_today_tip_card`, and UI action APIs without schema changes.

dream_customs/pipeline.py

@@ -312,6 +312,31 @@ def _answer_based_today_tip(answers: str, anchor: str, language: str = "en") ->
     return ""
 
 
+def _answer_based_interpretation(answers: str, anchor: str, language: str = "en") -> str:
+    lowered = (answers or "").lower()
+    if _is_zh(language):
+        if "邮件" in lowered or "email" in lowered:
+            return f"也许「{anchor}」不是在催你立刻完成什么，而是在提醒你：那封邮件可以先从一句话开始。"
+        if "消息" in lowered or "message" in lowered:
+            return f"也许「{anchor}」不是在催你立刻回应什么，而是在提醒你：那条消息可以先从一句草稿开始。"
+        return ""
+    if "email" in lowered:
+        return (
+            f"Maybe the {anchor} is not asking you to finish the overdue email at once. "
+            "It is pointing to the gentler threshold: opening it and writing one first sentence."
+        )
+    if "message" in lowered:
+        return (
+            f"Maybe the {anchor} is not asking you to answer every message at once. "
+            "It is pointing to the gentler threshold: opening one thread and drafting one first sentence."
+        )
+    return ""
+
+
+def _answer_bridge_anchor(anchors: List[str]) -> str:
+    return next((anchor for anchor in anchors if "14" in anchor), anchors[0])
+
+
 def _anchor_in_text(text: str, anchors: List[str]) -> bool:
     clean = (text or "").lower()
     for anchor in anchors:
@@ -594,7 +619,10 @@ def _polish_today_tip(card: TodayTipCard, intake: DreamIntake, answers: str = ""
         polished.dream_summary = _summary_from_intake(intake, language)
     if not polished.main_question.strip():
         polished.main_question = _main_question_from_intake(intake, language)
-    if not polished.interpretation.strip() or not _anchor_in_text(polished.interpretation, anchors):
+    answer_interpretation = _answer_based_interpretation(answers, _answer_bridge_anchor(anchors), language)
+    if answer_interpretation:
+        polished.interpretation = answer_interpretation
+    elif not polished.interpretation.strip() or not _anchor_in_text(polished.interpretation, anchors):
         polished.interpretation = _fallback_interpretation(intake, language)
     generic_tip_markers = ["drink water", "hydrate", "多休息", "保持积极", "take a walk"]
     answer_tip = _answer_based_today_tip(answers, anchors[0], language)

dream_customs/render.py

@@ -33,7 +33,7 @@ def render_today_tip_card(card: TodayTipCard, language: str = "en") -> str:
         "thanks": "谢谢你的分享。根据你的梦境，我们为你整理了今天的参考。"
         if is_zh
         else "Thanks for sharing this. Here is one grounded suggestion for today.",
-        "interpretation": "也许这个梦在提醒你" if is_zh else "Maybe this dream is pointing to",
+        "interpretation": "补充解读" if is_zh else "Supporting reflection",
         "today_tip": "今天的小建议" if is_zh else "Today's small suggestion",
         "tiny_action": "没试过的小事" if is_zh else "Tiny action",
         "anchors": "关键词：" if is_zh else "Anchors:",
@@ -73,14 +73,6 @@ def render_today_tip_card(card: TodayTipCard, language: str = "en") -> str:
       <p>{labels['thanks']}</p>
     </div>
   </div>
-  <article class="dqa-result-card is-interpretation">
-    <div class="dqa-card-icon">☘</div>
-    <div>
-      <h3>{labels['interpretation']}</h3>
-      <p>{escape(card.interpretation)}</p>
-      <div class="dqa-anchor-strip">{labels['anchors']} {anchors}</div>
-    </div>
-  </article>
   <article class="dqa-result-card is-primary-tip">
     <div class="dqa-card-icon">☼</div>
     <div>
@@ -90,6 +82,14 @@ def render_today_tip_card(card: TodayTipCard, language: str = "en") -> str:
     </div>
   </article>
   {tiny_action}
+  <article class="dqa-result-card is-interpretation">
+    <div class="dqa-card-icon">☘</div>
+    <div>
+      <h3>{labels['interpretation']}</h3>
+      <p>{escape(card.interpretation)}</p>
+      <div class="dqa-anchor-strip">{labels['anchors']} {anchors}</div>
+    </div>
+  </article>
   {qa_history}
   {safety}
   {caring_note}

scripts/evaluate_today_tip_quality.py

@@ -52,6 +52,13 @@ def evaluate_case(case: Dict[str, Any]) -> List[str]:
     view = _text_for_case(case)
     combined = "\n".join([view.get("card_title", ""), view.get("card_text", ""), view.get("card_html", "")])
     lowered = combined.lower()
+    interpretation = (
+        view.get("debug", {})
+        .get("session", {})
+        .get("draft_tip", {})
+        .get("interpretation", "")
+        .lower()
+    )
     failures: List[str] = []
 
     if view.get("status") != "tip":
@@ -60,6 +67,16 @@ def evaluate_case(case: Dict[str, Any]) -> List[str]:
     if not any(anchor.lower() in lowered for anchor in case.get("required_anchors", [])):
         failures.append("missing_required_anchor")
 
+    missing_answer_terms = [term for term in case.get("required_answer_terms", []) if term.lower() not in lowered]
+    if missing_answer_terms:
+        failures.append("missing_answer_terms:" + ",".join(missing_answer_terms))
+
+    missing_interpretation_terms = [
+        term for term in case.get("required_interpretation_terms", []) if term.lower() not in interpretation
+    ]
+    if missing_interpretation_terms:
+        failures.append("missing_interpretation_terms:" + ",".join(missing_interpretation_terms))
+
     old_terms = [term for term in OLD_CUSTOMS_TERMS if term in lowered]
     if old_terms:
         failures.append("old_customs_terms:" + ",".join(old_terms))

tests/fixtures/today_tip_eval_cases.json

@@ -11,7 +11,9 @@
     "dream_text": "I dreamed I was in an elevator where the floor buttons melted like wax. The number 14 kept blinking, and I felt late but strangely calm.",
     "mood": "Uneasy",
     "answer": "I want to make starting my overdue email easier without feeling trapped by it.",
-    "required_anchors": ["elevator", "button", "14"]
+    "required_anchors": ["elevator", "button", "14"],
+    "required_answer_terms": ["overdue email", "first sentence"],
+    "required_interpretation_terms": ["overdue email", "floor 14"]
   },
   {
     "id": "exam_without_pencil",

tests/test_render.py

@@ -1,6 +1,12 @@
 from dream_customs.pipeline import add_evidence, create_session
-from dream_customs.render import render_pact_card, render_pact_inspector, render_status_bar, render_timeline
-from dream_customs.schema import PactCard
+from dream_customs.render import (
+    render_pact_card,
+    render_pact_inspector,
+    render_status_bar,
+    render_timeline,
+    render_today_tip_card,
+)
+from dream_customs.schema import PactCard, TodayTipCard
 
 
 def test_render_pact_card_contains_core_fields():
@@ -72,3 +78,21 @@ def test_status_bar_is_status_not_fake_navigation():
     assert "Current: Empty desk" in html
     assert "dc-phase-rail" not in html
     assert "<nav" not in html
+
+
+def test_today_tip_card_prioritizes_tip_before_interpretation():
+    html = render_today_tip_card(
+        TodayTipCard(
+            dream_summary="You dreamed about an elevator.",
+            main_question="What feels hard to start?",
+            dream_anchors=["floor 14", "elevator"],
+            followup_questions=["What real task feels stuck?"],
+            user_answers=["An overdue email feels hard to start."],
+            interpretation="Maybe this dream is pointing to a stuck beginning.",
+            today_tip="Open the overdue email and write only the first sentence.",
+            tiny_action="Set a five-minute timer and stop after one sentence.",
+            caring_note="One line is enough for now.",
+        )
+    )
+
+    assert html.index("Today's small suggestion") < html.index("Maybe this dream is pointing to")

tests/test_ui_actions.py

@@ -160,3 +160,29 @@ def test_english_today_tip_has_no_chinese_anchor_leakage():
     assert "overdue email" in combined.lower()
     assert "first sentence" in combined.lower()
     assert "immediately" not in combined.lower()
+
+
+def test_english_interpretation_uses_user_answer_before_tip():
+    state, _view_json = submit_dream_action(
+        dream_text=(
+            "I dreamed I was in an elevator where the floor buttons melted like wax. "
+            "The number 14 kept blinking, and I felt late but strangely calm."
+        ),
+        mood="Uneasy",
+        text_backend="demo",
+        vision_backend="demo",
+        language="en",
+    )
+
+    _state, view_json = answer_to_card_action(
+        state,
+        "I want to make starting my overdue email easier without feeling trapped by it.",
+        text_backend="demo",
+        vision_backend="demo",
+        language="en",
+    )
+    view = json.loads(view_json)
+    interpretation_line = next(line for line in view["card_text"].splitlines() if line.startswith("Interpretation:"))
+
+    assert "overdue email" in interpretation_line.lower()
+    assert "floor 14" in interpretation_line.lower()