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

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

---
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:

{
  "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.