diff --git a/docs/superpowers/specs/2026-05-16-procurement-analysis-skill-design.md b/docs/superpowers/specs/2026-05-16-procurement-analysis-skill-design.md new file mode 100644 index 0000000..8d22d63 --- /dev/null +++ b/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=)`. 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=, limit=10–20)` | Build candidate table | +| DEEP_ANALYSIS | `describe_entity(entity_code)` → multiple `search_procurement_docs(query=, 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=)` 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.