docs(spec): procurement-analysis skill design

Workflow-level orchestrator skill spec for analyzing TBMT/KHLCNT/LCNT/E-HSMT
through 2 lenses (nhà thầu + chủ đầu tư) using existing 5 MCP tools.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-05-16-procurement-analysis-skill-design.md

@@ -0,0 +1,264 @@
+# Procurement Analysis Skill — Design Spec
+
+**Date:** 2026-05-16
+**Status:** Draft (awaiting user approval)
+**Repo:** `openclaw-egp-plugin`
+**Skill path:** `skills/procurement-analysis/SKILL.md`
+
+---
+
+## 1. Goal
+
+Add a workflow-level orchestrator skill to `openclaw-egp-plugin` that guides an OpenClaw agent to act as a domain expert + agentic RAG analyst over Vietnamese e-procurement documents (TBMT / KHLCNT / LCNT / E-HSMT) on the National Public Procurement Network.
+
+The skill turns the existing 5 tool-level skills (`search-procurement-docs`, `list-entities`, `describe-entity`, `fetch-raw-file`, `entity-types-glossary`) into a coherent analytical workflow with intent routing, evidence orchestration, and a fixed output schema.
+
+## 2. Non-goals
+
+- No per-industry skills (no `medical-tender`, `it-tender`, `construction-tender`). Industries are query keywords/filters only.
+- No new MCP tools. Skill orchestrates the 5 existing tools.
+- No new server endpoints, no DB schema change, no data model migration.
+- No knowledge-base content about procurement law/regulations in the skill — skill analyzes only what's in the retrieved documents.
+
+## 3. Approach (selected: A — Single orchestrator skill)
+
+- Keep the 5 thin tool-level skills unchanged. They give per-tool usage guidance.
+- Add **one new skill** `procurement-analysis` at workflow level.
+- Two-tier architecture: workflow skill (this) above, tool skills (existing) below. No overlap in `description:` fronmatter — the new skill describes business analysis, tool skills describe single-tool usage.
+- Plugin manifest gets one new entry in `skills` array; everything else unchanged.
+
+## 4. Skill file structure
+
+```
+skills/procurement-analysis/
+└── SKILL.md
+```
+
+Single file. No supporting Python/JS — skill is pure prompt content for the agent.
+
+## 5. SKILL.md — front matter
+
+```yaml
+---
+name: procurement-analysis
+description: Phân tích chuyên sâu hồ sơ đấu thầu Việt Nam (TBMT/KHLCNT/LCNT/E-HSMT) theo 2 góc nhìn nhà thầu + chủ đầu tư. Dùng khi user hỏi tìm/phân tích/audit/so sánh gói thầu — KHÔNG dùng cho tra cứu định nghĩa thuật ngữ hay tải file đơn lẻ.
+---
+```
+
+## 6. Intent routing
+
+Skill instructs the agent to classify the user query into one of four intents BEFORE any tool call:
+
+| Intent | Trigger signals | Output mode |
+|--------|----------------|-------------|
+| **DISCOVERY** | "tìm", "có gói nào", "các gói … đang mở", industry keyword (y tế, CNTT, xây lắp...) without entity_code | Candidate table (Section 7) — no full analysis |
+| **DEEP_ANALYSIS** | User names 1 entity_code, or asks "phân tích gói X", "nhà thầu cần chuẩn bị gì cho X" | Full 5-part schema (Section 8) |
+| **CROSS_DOC_AUDIT** | "TBMT/KHLCNT/E-HSMT có khớp không", "có sửa đổi không", "có gia hạn không" | Full 5-part schema + cross-doc compare table |
+| **RISK_AUDIT** | "rủi ro", "đã đăng đủ chưa", "có gì bất thường" | Full 5-part schema, emphasis on Section 5 |
+
+If the agent cannot classify confidently (signals overlap or are missing), it MUST ask the user to clarify before running any tool. It MUST NOT default to deep analysis.
+
+## 7. DISCOVERY mode output
+
+When intent = DISCOVERY:
+
+**Workflow:**
+1. Extract keyword/filter from user question: industry, goods/services, location, status, time window, value range if any.
+2. Retrieve candidate list using `list_entities(entity_type?)` + `search_procurement_docs(query=<extracted keyword>)`. Cap at top 10–20 results.
+3. Render the candidate table below — **do not** run full 5-part analysis for each item.
+4. End with: "Đây là danh sách candidate, chưa phải phân tích đầy đủ. Vui lòng chọn `entity_code` để chạy phân tích sâu." Suggest refinement filters if results > 20.
+5. If any candidate has urgent deadline or visible risk indicator, list it under "Ưu tiên xem trước" before the table.
+
+**Candidate table columns:**
+- `rank`
+- `entity_type`
+- `entity_code`
+- `tên gói / thông báo / kế hoạch`
+- `bên mời thầu / chủ đầu tư` (if available)
+- `giá gói thầu` (if available)
+- `deadline / đóng thầu` (if available)
+- `trạng thái` (if available)
+- `highlight ngắn`: match reason or noteworthy point
+- `citation / source`
+
+**Triggers that bypass DISCOVERY and go straight to DEEP_ANALYSIS:**
+- User explicitly says "phân tích luôn top 3 / top 5".
+- Search returns exactly 1 candidate with high relevance.
+
+## 8. DEEP_ANALYSIS output schema (5 parts)
+
+This schema is rendered when intent = DEEP_ANALYSIS, CROSS_DOC_AUDIT, or RISK_AUDIT.
+
+### Part 1 — Tóm tắt gói thầu
+
+- Mã TBMT/E-TBMT
+- Mã KHLCNT
+- Tên gói thầu
+- Chủ đầu tư / Bên mời thầu
+- Trạng thái: đang mở / đã đóng / đã hủy / đã gia hạn — **only conclude when `bidCloseDate` / `status` / explicit source field is present**; otherwise: "không xác định từ nguồn đã truy xuất".
+- One-sentence intent-aware conclusion.
+
+### Part 2 — Thông tin KHLCNT / TBMT / E-HSMT quan trọng
+
+Compact comparison table:
+
+| Trường | KHLCNT | TBMT | E-HSMT |
+|--------|--------|------|--------|
+| Giá gói thầu | … | … | — |
+| Nguồn vốn | … | … | — |
+| Hình thức LCNT | … | … | … |
+| Phương thức LCNT | … | … | … |
+| Loại hợp đồng | … | … | … |
+| Thời gian thực hiện | … | … | … |
+| Bảo đảm dự thầu | — | … | … |
+| Thời điểm phát hành / đóng / mở thầu | — | … | … |
+| Chia lô | … | … | … |
+| Địa điểm | … | … | … |
+
+Missing fields → "không thấy trong nguồn đã truy xuất". Never blank, never guessed.
+
+### Part 3 — Phân tích theo góc nhìn nhà thầu
+
+When intent is bidder-focused → render full bullet list below. When intent is publisher-focused or audit → render header with suffix `(không phải trọng tâm câu hỏi, rút gọn)` and keep only 2–3 conclusion bullets.
+
+Bullets:
+- **Điều kiện tham dự**: tư cách hợp lệ, liên danh, nhà thầu phụ, bảo đảm dự thầu (giá trị + hình thức).
+- **Năng lực & kinh nghiệm yêu cầu**: hợp đồng tương tự, doanh thu, nhân sự chủ chốt, thiết bị.
+- **Tiêu chuẩn đánh giá**: hợp lệ / kỹ thuật / tài chính / giá — đạt-không-đạt hoặc chấm điểm; trọng số nếu có.
+- **Phạm vi & danh mục**: HHDV / công việc / chia lô / địa điểm giao.
+- **Hồ sơ cần chuẩn bị (checklist)**: E-HSDT, đơn dự thầu, bảo lãnh, biểu giá, đề xuất KT, đề xuất TC, tài liệu chứng minh.
+- **Rủi ro tham dự**: deadline gấp / tiêu chí khó / chứng minh nặng / thiếu thông tin → đề xuất gửi yêu cầu làm rõ.
+- **Kết luận tham dự**: ① Nên xem xét tham dự / ② Cần kiểm tra thêm / ③ Rủi ro cao — kèm lý do.
+
+### Part 4 — Phân tích theo góc nhìn chủ đầu tư / bên mời thầu
+
+When intent is publisher-focused or audit → full bullet list. Otherwise → suffix and 2–3 conclusion bullets.
+
+Bullets:
+- **Audit KHLCNT**: đủ phê duyệt / giá / nguồn vốn / hình thức&phương thức / loại HĐ / thời gian thực hiện?
+- **Audit TBMT**: đủ mã / tên gói / bên mời / chủ đầu tư / mốc thời gian / bảo đảm / trạng thái?
+- **Audit E-HSMT**: đủ Chỉ dẫn NT / Bảng dữ liệu / Tiêu chuẩn ĐG / YC kỹ thuật / Biểu mẫu / Điều kiện HĐ / Mẫu HĐ?
+- **Khớp giữa 3 hồ sơ** (chỉ render khi CROSS_DOC_AUDIT or related docs available): bảng so sánh field-by-field, ✓ / ✗ / "không kiểm tra được".
+- **Sửa đổi / gia hạn / làm rõ**: có hay không, phiên bản mới nhất.
+- **Kết luận audit**: ① Đủ để công khai / ② Cần bổ sung / ③ Rủi ro cần rà soát pháp lý — kèm lý do.
+
+### Part 5 — Rủi ro, điểm cần làm rõ & nguồn trích dẫn
+
+- **Rủi ro & cảnh báo** — bulleted; each bullet has inline citation.
+- **Câu hỏi / dữ liệu cần bổ sung** — bullet list of what's missing for completeness.
+- **Nguồn trích dẫn** — final table for every important claim in Parts 3 & 4:
+
+| entity_code | source_file | page | mục/section | chunk_id | link_status |
+|-------------|-------------|------|-------------|----------|-------------|
+
+## 9. Citation rules
+
+**Format:** `[entity_code | source_file | page=N | mục/section nếu có | chunk_id nếu có | link_status=confirmed|inferred]`
+
+**Required fields per claim:** `entity_code`, `source_file`, `page`.
+
+**Missing-page rule:** when the retrieval tool does not return a page for a chunk, write `page=không có trong metadata`. Never omit the page field.
+
+**Section/mục rule:** only fill `mục/section` when the chunk text itself contains a heading (e.g., "Chương III, mục 2.1"). Never infer a heading from surrounding context.
+
+**chunk_id rule:** include if the tool returns it. Currently `search_procurement_docs` does not return `chunk_id` directly; treat as optional. (Future server work may add it.)
+
+**Multi-source claim rule:** when a claim aggregates information from multiple chunks/files, cite all source rows or end the citation with "tổng hợp từ nhiều nguồn".
+
+**link_status rule:**
+- `confirmed` — user provided the related code, OR one document's text explicitly names the other document's code.
+- `inferred` — link discovered via fuzzy code match, prefix/substring, similarity, or content-based search. Any cross-doc claim resting on `inferred` link MUST be prepended with "Suy luận, cần xác nhận".
+
+## 10. Anti-hallucination rules (skill MUST instruct agent to follow)
+
+1. **Strict type discrimination**: KHLCNT (kế hoạch) ≠ TBMT (thông báo) ≠ LCNT (quy trình) ≠ E-HSMT (hồ sơ điện tử). Never conflate.
+2. **No inference filler**: when a field is absent, write "không thấy trong nguồn đã truy xuất". Never substitute with "thường thì..." or general industry knowledge.
+3. **"Không thấy" ≠ "không có"**: missing-from-retrieval does not imply the field is absent from reality. Never restate the former as the latter.
+4. **Multi-evidence requirement**: do not draw conclusions from only the top-1 result. Inspect at least 3–5 results; if fewer than 3 hits, expand the query or rephrase before concluding insufficient evidence.
+5. **Hit-count transparency**: when total hits < 3, report the actual hit count and explicitly note evidence is incomplete.
+6. **Status conclusion gate**: do not conclude "đang mở / đã đóng / đã hủy" unless `bidCloseDate`, `status`, or a source field explicitly states it.
+7. **Conclusion strength gate**: when citation is weak (≤ 1 cite, or cite content doesn't match the claim), drop strong conclusions ("nên tham dự" / "đủ để công khai" / "rủi ro pháp lý") and fall back to "cần kiểm tra thêm" or "không đủ dữ liệu để kết luận".
+8. **Retrieval-weakness reporting**: if results = [] or `limitations` warning present, state the limit and propose extra files / keywords / refinements.
+9. **Ambiguous industry keyword expansion**: when the industry keyword is vague (e.g., "y tế" → may cover thiết bị, dược, vật tư, dịch vụ y tế), the agent MAY expand the query with business-relevant synonyms — but MUST log the exact keywords used in the response.
+
+## 11. Tool orchestration mapping
+
+| Intent | Tools to call (in order) | Purpose |
+|--------|--------------------------|---------|
+| DISCOVERY | `list_entities(entity_type?)` → `search_procurement_docs(query=<keywords>, limit=10–20)` | Build candidate table |
+| DEEP_ANALYSIS | `describe_entity(entity_code)` → multiple `search_procurement_docs(query=<field-specific>, entity_code=...)` for: giá, nguồn vốn, deadline, tiêu chuẩn đánh giá, năng lực, tiêu chí kỹ thuật, bảo đảm dự thầu, biểu mẫu | Fill 5-part schema |
+| CROSS_DOC_AUDIT | `list_entities` (fuzzy code candidates) → `search_procurement_docs(query=<code A>)` to find mentions of A inside B's text → if > 1 candidate, ASK USER → field-by-field compare via `search_procurement_docs` per field | Compare KHLCNT vs TBMT vs E-HSMT |
+| RISK_AUDIT | Same as DEEP_ANALYSIS + completeness checklist for E-HSMT mandatory sections | Highlight Part 5 |
+
+Skill must not over-explain HOW each tool works — that's the job of the 5 thin tool-level skills. This skill says only WHICH tool to use WHEN.
+
+## 12. Industry keyword handling
+
+User says "y tế" / "CNTT" / "xây lắp" / "tư vấn" / "dược":
+1. Extract keyword(s).
+2. Use as `query` for `search_procurement_docs` and post-hoc filter on `list_entities`.
+3. Output remains the common schema. Industry is filter input only.
+4. If keyword is vague, expand with documented synonyms (see Rule 11.9) and log the expansion.
+
+No industry-specific section, sub-skill, or template is created.
+
+## 13. Anti-patterns (skill MUST list explicitly)
+
+- ❌ Trả lời từ trí nhớ / kiến thức nền thay vì gọi tool.
+- ❌ Chỉ gọi 1 tool rồi kết luận — phải orchestrate (list + search + describe).
+- ❌ Lấy top-1 result làm sự thật duy nhất.
+- ❌ Gộp KHLCNT/TBMT/LCNT/E-HSMT thành một khái niệm "hồ sơ".
+- ❌ Kết luận trạng thái khi không có mốc thời gian / `status` field.
+- ❌ Cite chung chung "theo hồ sơ" — phải đủ `entity_code + source_file + page`.
+- ❌ Bỏ trống `page` thay vì ghi `page=không có trong metadata`.
+- ❌ Suy diễn cross-doc link mà không gắn `link_status=inferred` + cảnh báo "Suy luận, cần xác nhận".
+- ❌ Skip "cần kiểm tra thêm" để ra kết luận mạnh khi cite yếu.
+- ❌ Chuyển "không thấy trong nguồn đã truy xuất" thành "không có" trong gói thầu.
+- ❌ Tạo Section ngành riêng (vd. "phân tích y tế") — schema phải common.
+- ❌ Render full 5-part cho discovery query (chỉ candidate table + summary ngắn trừ khi user yêu cầu rõ).
+- ❌ Mở rộng keyword ngành bằng synonym mà không log keyword đã dùng.
+
+## 14. Manifest update
+
+Edit `openclaw.plugin.json`:
+
+```json
+{
+  "skills": [
+    "skills/search-procurement-docs",
+    "skills/list-entities",
+    "skills/describe-entity",
+    "skills/fetch-raw-file",
+    "skills/entity-types-glossary",
+    "skills/procurement-analysis"
+  ]
+}
+```
+
+Bump `version` from `0.1.0` to `0.2.0`.
+
+## 15. Verification
+
+The skill is content-only (no code). Verification steps:
+
+1. **Manifest validation**: `openclaw.plugin.json` parses, `skills` array references existing folder, version bumped.
+2. **Frontmatter validation**: SKILL.md has valid YAML frontmatter with `name` + `description`.
+3. **Content review**: spec sections 6–13 are present in SKILL.md (intent routing, both output modes, citation rules, anti-hallucination rules, tool mapping, industry handling, anti-patterns).
+4. **Manual smoke test** (post-install): invoke each of the 6 example user queries from the original brainstorm prompt and verify the agent picks `procurement-analysis` (not the wrong tool skill) and follows the expected workflow:
+   - "Tìm hồ sơ mời thầu y tế" → DISCOVERY → candidate table.
+   - "Phân tích E-HSMT IB2600186834-01" → DEEP_ANALYSIS → 5-part schema.
+   - "Gói IB2600186834-01 nhà thầu cần chuẩn bị gì?" → DEEP_ANALYSIS, Part 3 expanded.
+   - "Hồ sơ IB2600186834-01 có rủi ro gì không?" → RISK_AUDIT, Part 5 expanded.
+   - "TBMT IB2600186834-01 và KHLCNT có khớp nhau không?" → CROSS_DOC_AUDIT → hybrid candidate resolution → compare table.
+   - "Bên mời thầu IB2600186834-01 đã đăng đủ thông tin chưa?" → RISK_AUDIT, Part 4 expanded.
+
+## 16. Tagging / release
+
+After commit + skill content review, tag plugin repo `v0.2.0` to align with the manifest version bump.
+
+## 17. Out of scope (explicitly deferred)
+
+- Adding a `package_id` foreign key in the server DB to link KHLCNT ↔ TBMT ↔ E-HSMT natively. The hybrid heuristic in Section 11 covers the cross-doc audit use case meanwhile.
+- Returning `chunk_id` + `section_heading` from `search_procurement_docs`. Today's payload is sufficient for the citation format; richer fields can be added later without breaking the skill.
+- Multi-language support. Skill output is Vietnamese only.
+- Programmatic schema validation of agent output. The 5-part schema is for the agent to follow, not for automated checking in this iteration.