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

```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 AND the retrieval tool flags it as a strong match (score top-1 noticeably above next candidate; agent uses judgment). If in doubt, stay in DISCOVERY and ask the user to confirm.

## 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 | … | … | … |

Cell semantics:
- `…` — placeholder for actual value extracted from the document.
- `—` (em dash) — field intentionally not applicable for that document type (e.g., "Bảo đảm dự thầu" doesn't apply to KHLCNT).
- `không thấy trong nguồn đã truy xuất` — field applies in principle but was not found in retrieved chunks.

Never blank, never guessed. Never render `…` literally in agent output.

### 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.