fix: make build plans more builder-facing

Co-authored-by: Codex <noreply@openai.com>

data/sample_trace.jsonl

@@ -1,4 +1,4 @@
-{"app": "hackathon-advisor", "generated_at": "2026-06-07T00:18:31+00:00", "idea_count": 2, "index": {"algorithm": "tfidf-sparse-v1", "index_generated_at": "2026-06-06T19:44:42+00:00", "snapshot_digest": "1d59c168b446bc1268ef648897fac523e85b258fd6048a37409b9cfbc5c28329", "snapshot_generated_at": "2026-06-06T19:20:47+00:00"}, "schema_version": 1, "turn_count": 3, "type": "trace_manifest"}
+{"app": "hackathon-advisor", "generated_at": "2026-06-07T03:39:50+00:00", "idea_count": 2, "index": {"algorithm": "tfidf-sparse-v1", "index_generated_at": "2026-06-06T19:44:42+00:00", "snapshot_digest": "1d59c168b446bc1268ef648897fac523e85b258fd6048a37409b9cfbc5c28329", "snapshot_generated_at": "2026-06-06T19:20:47+00:00"}, "schema_version": 1, "turn_count": 3, "type": "trace_manifest"}
 {"artifact_title": "A local-first archive cartographer for family photos", "input": "A local-first archive cartographer for family photos", "overall": 4.9, "plan_steps": 0, "response": "The ink bleeds around A local-first archive cartographer for family photos. Closest echoes: page 30: Family Bill Assistant; page 45: Kasualdad LFED; page 55: Mycelium. The seal reads ECHO x4 at 4.9/10. Keep the audience, but change the mechanism or artifact so the demo proves a gap instead of joining a cluster.", "schema_version": 1, "tool_resolution": {"call": {"arguments": {"pitch": "A local-first archive cartographer for family photos", "title": "A local-first archive cartographer for family photos"}, "name": "save_idea"}, "errors": [], "status": "valid"}, "tools": [{"name": "save_idea", "summary": "Wrote idea page 'A local-first archive cartographer for family photos'."}, {"name": "search_projects", "summary": "Checked 5 closest project echoes."}, {"name": "score_idea", "summary": "Pressed a five-quadrant seal: 4.9/10."}], "turn_index": 1, "type": "agent_turn", "verdict": "ECHO x4"}
 {"artifact_title": "Hands-on science coach", "input": "write bolder and find whitespace", "overall": 6.0, "plan_steps": 0, "response": "Gold gathers on Hands-on science coach. A lab-notebook companion that designs safe experiments from household materials. No close project echoes in the current snapshot. The seal reads UNWRITTEN at 6.0/10. The next move is to make one concrete before/after scene and cite the two weakest nearby echoes in the margin.", "schema_version": 1, "tool_resolution": {"call": {"arguments": {}, "name": "find_whitespace"}, "errors": [], "status": "valid"}, "tools": [{"name": "find_whitespace", "summary": "Ranked 4 under-explored regions."}, {"name": "save_idea", "summary": "Wrote idea page 'Hands-on science coach'."}, {"name": "score_idea", "summary": "Pressed a five-quadrant seal: 4.8/10."}], "turn_index": 2, "type": "agent_turn", "verdict": "UNWRITTEN"}
-{"artifact_title": "Hands-on science coach", "input": "make a build plan", "overall": 6.0, "plan_steps": 6, "response": "The wax seal for Hands-on science coach reads 6.0/10, UNWRITTEN. The build path is: 1. Lock a one-sentence promise and one demo input that proves originality. 2. Compare against the nearest echoes, then sharpen the part only this idea can own. 3. Build the smallest happy path: input, citations, score seal, and shareable artifact. 4. Add one goal hook only after the core loop is smooth enough to demo without narration. 5. Prepare a tiny LoRA dataset from successful advisor turns before training. 6. Record the trace and write build notes from the exact decisions.", "schema_version": 1, "tool_resolution": {"call": {"arguments": {}, "name": "make_plan"}, "errors": [], "status": "valid"}, "tools": [{"name": "score_idea", "summary": "Pressed a five-quadrant seal: 4.8/10."}, {"name": "make_plan", "summary": "Drafted 6 build steps."}], "turn_index": 3, "type": "agent_turn", "verdict": "UNWRITTEN"}
+{"artifact_title": "Hands-on science coach", "input": "make a build plan", "overall": 6.0, "plan_steps": 6, "response": "The wax seal for Hands-on science coach reads 6.0/10, UNWRITTEN. The build path is: 1. Lock a one-sentence promise and one test input that proves what is different. 2. Compare against the nearest echoes, then sharpen the part only this idea can own. 3. Build the smallest happy path: input, nearby project citations, score, and one shareable output. 4. Add one selected-goal feature only after the core loop is smooth enough to explain without narration. 5. Collect successful advisor examples before training a tiny LoRA. 6. Write build notes from the exact decisions, screenshots, and outputs.", "schema_version": 1, "tool_resolution": {"call": {"arguments": {}, "name": "make_plan"}, "errors": [], "status": "valid"}, "tools": [{"name": "score_idea", "summary": "Pressed a five-quadrant seal: 4.8/10."}, {"name": "make_plan", "summary": "Drafted 6 build steps."}], "turn_index": 3, "type": "agent_turn", "verdict": "UNWRITTEN"}

hackathon_advisor/tools.py

@@ -24,7 +24,7 @@ GOAL_PROFILE_BY_ID = {
     },
     "Well-Tuned": {
         "label": "Trainable",
-        "description": "Shape good turns into a tiny fine-tune dataset.",
+        "description": "Shape good examples into a tiny fine-tune dataset.",
     },
     "Off-Brand": {
         "label": "Distinct voice",
@@ -40,7 +40,7 @@ GOAL_PROFILE_BY_ID = {
     },
     "Field Notes": {
         "label": "Build notes",
-        "description": "Keep decisions easy to write up from the session trace.",
+        "description": "Keep decisions easy to write up from the saved session.",
     },
 }
 
@@ -151,11 +151,11 @@ class AdvisorTools:
 
     def make_plan(self, idea: Idea, profile: dict[str, Any] | None = None) -> tuple[list[str], ToolEvent]:
         plan = [
-            "Lock a one-sentence promise and one demo input that proves originality.",
+            "Lock a one-sentence promise and one test input that proves what is different.",
             "Compare against the nearest echoes, then sharpen the part only this idea can own.",
-            "Build the smallest happy path: input, citations, score seal, and shareable artifact.",
-            "Add one goal hook only after the core loop is smooth enough to demo without narration.",
-            "Record the trace and write build notes from the exact decisions.",
+            "Build the smallest happy path: input, nearby project citations, score, and one shareable output.",
+            "Add one selected-goal feature only after the core loop is smooth enough to explain without narration.",
+            "Write build notes from the exact decisions, screenshots, and outputs.",
         ]
         profile_steps = profile_plan_steps(profile)
         if profile_steps:
@@ -163,7 +163,7 @@ class AdvisorTools:
         if any("Well" in goal for goal in idea.goals):
             plan.insert(
                 max(0, len(plan) - 1),
-                "Prepare a tiny LoRA dataset from successful advisor turns before training.",
+                "Collect successful advisor examples before training a tiny LoRA.",
             )
         return plan, ToolEvent("make_plan", f"Drafted {len(plan)} build steps.")
 

tests/test_agent.py

@@ -86,6 +86,8 @@ def test_plan_command_uses_current_idea() -> None:
     assert planned.plan
     assert planned.artifact["title"] == first.artifact["title"]
     assert planned.state["ideas"][0]["title"] == first.artifact["title"]
+    assert all("Record the trace" not in step for step in planned.plan)
+    assert all("session trace" not in step for step in planned.plan)
 
 
 def test_non_plan_turns_clear_stale_build_plan() -> None:
@@ -275,6 +277,7 @@ def test_well_tuned_goal_adds_training_step_to_plan() -> None:
 
     assert first.state["ideas"][0]["goals"] == ["Well-Tuned"]
     assert any("LoRA" in step for step in planned.plan)
+    assert all("advisor turns" not in step for step in planned.plan)
 
 
 def test_planner_score_idea_scores_current_idea() -> None:

tests/test_app.py

@@ -46,6 +46,7 @@ def test_bootstrap_exposes_index_metadata() -> None:
     assert "description" in payload["goal_profiles"][0]
     assert "skills" in payload["profile_fields"]
     assert "prize_ledger" not in payload
+    assert all("trace" not in goal["description"].lower() for goal in payload["goal_profiles"])
 
 
 def test_trace_artifact_endpoint_exports_jsonl() -> None:
@@ -72,7 +73,7 @@ def test_field_notes_endpoint_exports_markdown() -> None:
     assert "Goals: Build notes" in payload
     assert "Targets: Field Notes" not in payload
     assert "## Turn Trace" in payload
-    assert "Record the trace and write build notes" in payload
+    assert "Write build notes from the exact decisions" in payload
 
 
 def test_chapter_endpoint_exports_markdown() -> None:

tests/test_field_notes.py

@@ -30,7 +30,7 @@ def test_field_notes_markdown_contains_session_decisions() -> None:
     assert "Targets: Field Notes" not in markdown
     assert "A local-first archive cartographer for family photos" in markdown
     assert "## Build Plan" in markdown
-    assert "Record the trace and write build notes" in markdown
+    assert "Write build notes from the exact decisions" in markdown
     assert "Closest cited Spaces" in markdown
     assert "Page " in markdown
     assert "## Wood Map" in markdown

tests/test_trace_export.py

@@ -38,4 +38,5 @@ def test_checked_in_sample_trace_matches_schema() -> None:
     assert "Add one prize" not in sample_text
     assert "set_target" not in sample_text
     assert "side_quests" not in sample_text
-    assert "Record the trace and write build notes from the exact decisions." in lines[-1]["response"]
+    assert "Record the trace" not in sample_text
+    assert "Write build notes from the exact decisions" in lines[-1]["response"]