# 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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
curl -s http://127.0.0.1:8000/healthz
```

Expected:
```json
{"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**

```bash
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"
```