feat: add self-reflection step before presenting roadmap

[jwm4]

Summary

Implements the self-reflection pattern from issue #6, where the agent reviews its own output before presenting it to users. This catches issues like missing files, generic advice, or unclear reasoning—improving quality without manual review.

Changes

New Node: reflect_on_roadmap

• Evaluates the generated roadmap against quality criteria
• Checks for: completeness, logical order, specificity, and accuracy
• Returns structured JSON feedback if issues are found

Conditional Routing

• After draft_roadmap, the workflow routes to reflection
• If reflection fails, loops back to draft_roadmap with feedback
• Maximum 2 retry iterations to prevent infinite loops

CLI Flag

• Added --no-reflection flag to skip reflection for faster results
• Reflection is enabled by default

Architecture

analyze_structure → context_expansion → draft_roadmap → reflect_on_roadmap → [pass?] → END
                                              ↑                    │
                                              └────── [retry] ─────┘

Testing

• Added 5 new tests for the reflection node
• Added 8 new tests for graph conditional routing
• All 70 tests pass with 85% coverage

Closes #6

[jwm4]

🗺️ Auto-Generated Review Roadmap

This roadmap was automatically generated by review-roadmap.
Model: anthropic-vertex/claude-opus-4-5

---

Review Roadmap for PR #7: Self-Reflection Step

High-Level Summary

This PR implements a self-reflection pattern where the agent reviews its own generated roadmap before presenting it to users. The key addition is a feedback loop: after drafting a roadmap, a new reflect_on_roadmap node evaluates quality criteria and can trigger a retry (up to 2 iterations). Users can opt-out via --no-reflection.

---

Recommended Review Order

1. State Model First (Foundation)

Start with state.py to understand the new state fields being threaded through the workflow:

• Look for new fields: reflection_feedback, reflection_passed, reflection_iterations, skip_reflection
• Verify the docstring accurately describes the workflow progression (line ~20-30 area based on truncation)

2. Prompts (The Reflection Criteria)

Review prompts.py next:

• Look for MAX_REFLECTION_ITERATIONS constant (referenced in graph.py)
• Check the reflection prompt template—what quality criteria does it evaluate?
• Ensure the prompt asks for structured JSON feedback (mentioned in PR description)

3. Node Implementation (Core Logic)

The nodes.py file contains the new reflect_on_roadmap function:

• Verify it's imported at the top alongside other nodes
• Check the reflection node parses JSON correctly and handles malformed responses
• Confirm it populates reflection_feedback, reflection_passed, and increments reflection_iterations

4. Graph Workflow (Orchestration)

With understanding of state and nodes, review graph.py:

• Line ~23: _should_reflect — routing logic for skip_reflection flag
• Line ~36: _after_reflection — retry vs end decision
• Verify the graph wiring matches the architecture diagram in the PR description
• Check that MAX_REFLECTION_ITERATIONS prevents infinite loops (line ~44)

5. Entry Point

Review main.py:

• Look for --no-reflection CLI flag definition
• Verify it propagates to state initialization correctly

6. Test Suite

Review tests in order of dependency:

1. conftest.py — new fixtures for reflection testing
2. test_agent_nodes.py — 5 new tests for reflection node
3. test_agent_graph.py — 8 new tests for conditional routing

7. Documentation

Finish with README.md to verify user-facing docs match implementation.

---

Watch Outs

Logic Concerns

1. Infinite loop prevention: Verify MAX_REFLECTION_ITERATIONS is actually checked before calling draft_roadmap again, not after
2. State mutation on retry: When retrying, does draft_roadmap receive the reflection_feedback? Check if the node reads this field
3. Iteration counter: Confirm reflection_iterations is incremented in reflect_on_roadmap, not in the routing function

Edge Cases

4. JSON parsing in reflection node: What happens if the LLM returns invalid JSON? Look for try/except handling
5. Empty roadmap: Does reflection handle the case where state.roadmap is empty/whitespace?
6. Skip + iteration state: If skip_reflection=True, ensure reflection_passed is set to a sensible default (or ignored downstream)

Testing Gaps

7. Retry path test: Verify there's a test that exercises the full retry loop (fail → feedback → regenerate → pass)
8. Max iterations test: Confirm a test exists for hitting the iteration limit and exiting gracefully

Security/Performance

9. LLM call count: Each retry adds 2 LLM calls (draft + reflect). With max 2 retries, that's up to 6 calls for roadmap generation. Is this documented?

---

Existing Discussions

No comments have been left on this PR yet. You'll be the first reviewer—consider focusing on the core logic in graph.py and nodes.py where the feedback loop lives.