PMFlow/docs/superpowers/plans/2026-04-19-external-signal-recommendation-content-upgrade.md

External Signal Recommendation Content Upgrade 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: Make recommendation-only external signal-source answers produce concrete, business-natural candidates with reasons instead of abstract boundary talk.

Architecture: Keep the new interaction-boundary routing intact, but add a recommendation content layer in external_query_service that first builds a structured recommendation packet and then renders user-facing natural Chinese. Route correctness stays in semantic planning; candidate quality and wording live in the recommendation packet and presenter.

Tech Stack: Python 3.11, Pydantic, existing PMFlow LLM service, pytest

---

Task 1: Lock Business-Natural Recommendation Expectations

Files:

• Modify: backend/tests/test_external_query_planner.py

• Modify: backend/tests/test_feishu_card_action_contract.py

• Step 1: Write failing tests for concrete recommendation candidates

Add tests that require:

• at least 3 concrete candidate signal-source types

• each candidate has a business reason

• different project contexts produce meaningfully different candidates

• answer text avoids architect jargon like “主链 / 这一层 / packet / analysis”

• Step 2: Run focused tests to verify they fail

Run:

cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_external_query_planner.py -k "signal_source_recommendation or recommendation" -q

Expected: FAIL on missing concrete candidates / wording assertions.

• Step 3: Add Feishu rendering red tests

Add a rendered-text test that requires final recommendation replies to look like business advice, not route/boundary analysis.

• Step 4: Run Feishu recommendation tests to verify they fail

Run:

cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_feishu_card_action_contract.py -k "recommendation" -q

Expected: FAIL on abstract / non-concrete output.

Task 2: Add Recommendation Packet Contracts

Files:

• Modify: backend/app/services/external_query_service/schemas.py

• Modify: backend/app/services/external_query_service/presenter.py

• Step 1: Add structured recommendation candidate models

Define minimal packet models for:

• recommendation candidate name

• business value reason

• project relevance / watch point

• Step 2: Add packet validation tests implicitly through presenter tests

No separate schema-only test unless needed; keep packet surface small.

Task 3: Build Concrete Recommendation Candidates

Files:

• Modify: backend/app/services/external_query_service/presenter.py

• Modify: backend/app/config/ai_prompts_catalog/part_scenes_06.py

• Modify: backend/app/config/ai_prompts.py

• Modify: backend/app/config/ai_prompts_catalog/__init__.py

• Step 1: Build a structured recommendation packet first

Implement presenter flow:

• use generate_structured_object when available

• grounded by project summary, recommendation goal, object anchors, objectives, and source summaries

• fallback to deterministic business-safe packet if structured generation fails

• Step 2: Render packet into natural business Chinese

Render to:

• one short lead sentence

• 1 / 2 / 3 concrete candidates

• each with a plain-language reason

• one short caveat that this is recommendation, not confirmed integration

• Step 3: Keep wording constraints

Reject or rewrite answers that:

• leak internal terms

• drift into architecture tone

• only say “信息不足 / 先不判断”

• Step 4: Run focused tests and make them pass

Run:

cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_external_query_planner.py backend/tests/test_feishu_card_action_contract.py -k "recommendation" -q

Expected: PASS

Task 4: Verify Project Variation and Runtime Safety

Files:

• Modify: backend/tests/test_external_query_planner.py

• Modify: backend/tests/test_feishu_card_action_contract.py

• Step 1: Add cross-project variation checks

Use business scenarios such as:

• 自动开票系统
• AI客服
• 门店库存异常日报助手

Require that candidate sets differ in sensible ways.

• Step 2: Run broader affected backend slice

Run:

cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && PYTHONPATH=backend /Users/yuuuu/Documents/AIProjectManger/backend/venv/bin/python -m pytest backend/tests/test_external_query_planner.py backend/tests/test_feishu_card_action_contract.py backend/tests/test_ai_pmo_ingress_mainline.py -q

Expected: PASS

Task 5: Final Verification and Runtime Refresh

Files:

• Modify if behavior/docs changed: docs/architecture/RUNTIME_GUARDRAILS.md, docs/architecture/CODE_REFERENCE_INDEX.md, docs/architecture/ARCHITECTURE_INVENTORY.md, CLAUDE.md

• Step 1: Run compile verification

Run:

cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && python3 -m py_compile backend/app/services/external_query_service/presenter.py backend/app/services/external_query_service/schemas.py

Expected: no output

• Step 2: Rebuild backend

Run:

cd /Users/yuuuu/Documents/AIProjectManger/.worktrees/codex/unified-project-ai-handoff && docker compose -p aiprojectmanger --env-file /Users/yuuuu/Documents/AIProjectManger/.env up -d --build backend

Expected: backend container recreated successfully

• Step 3: Check health

Run:

curl -s http://127.0.0.1:8000/healthz

Expected:

{"code":0,"message":"success","data":{"status":"ok"}}

• Step 4: Export business-style live IO samples

Capture 3-5 recommendation examples with:

• natural business inputs

• final model reply

• per-case score

• Step 5: Commit

git add backend/app/services/external_query_service backend/tests docs/architecture CLAUDE.md docs/superpowers/plans/2026-04-19-external-signal-recommendation-content-upgrade.md
git commit -m "feat: improve external signal recommendation content"