harvest

name	harvest
description	Knowledge harvesting — surface, distil, store, and recall tacit business knowledge. Run the Recall → Codebase-first → Grill → Distil → Confirm loop when a task needs a business fact that is not written down (why "予約" is always "reservation", when a feedback is a CR vs a Bug, which flow touches payments). Invokable by kopi-brse, kopi-implement, and any kopi agent that hits a business-knowledge gap. Writes verified facts to knowledge/.
license	MIT
allowed-tools	["file-search","bash"]

Harvest Skill

Convert tacit business knowledge (in a human's head, or scattered across ClickUp/GDocs) into distilled, human-verified knowledge files under knowledge/. Recall them on the next session instead of re-asking.

No engine. No vector DB. No embedding. No daemon. This is prompt + files + git only — constitution Article IV (No Custom Orchestrator) and Article VII (Simplicity Gate). Recall = file-search + grep over markdown. Versioning = git history.

Trigger Phrases

• "we keep re-explaining this business rule"
• "capture this knowledge / write this down"
• "harvest what we just learned"
• "why is this the rule? remember this for next time"
• A kopi agent detects a business-intent gap it cannot answer from code.

When NOT to use

• The answer is in the codebase → just grep/read it (that is Step 1, not a full harvest). Only persist a knowledge file when a human confirms a non-obvious business fact.
• Pure term translation → that already lives in glossary/. Add a knowledge file only for rules/decisions, not single-word mappings.

The loop

Step 0 RECALL ──► Step 1 CODEBASE-FIRST ──► Step 2 GRILL ──► Step 3 DISTIL ──► Step 4 CONFIRM
   read knowledge/      grep before asking       ask human         write knowledge/   human approves
        ▲                                        one Q at a time    file (_TEMPLATE)        │
        └──────────────────────── Step 5 UPDATE (supersede / re-verify) ◄──────────────────┘

Step 0 — RECALL (always first; never skip)

Before asking a human or assuming any business fact:

1. Read knowledge/INDEX.md (the map) — and the target repo's own knowledge/INDEX.md if the task is project-specific.
2. grep the knowledge/ files by topic, scope, type, and status: active for anything relevant; Read the matches.
3. Check glossary/core-terms.yaml and glossary/ui-patterns.yaml for terms.

If an active knowledge file already answers the question → use it and stop. If it is stale or looks wrong → go to Step 5 (Update). Only the still-missing part proceeds to grill. Be tolerant of OKF interop quirks: keep unknown frontmatter fields, accept unknown types, ignore dangling cross-links.

Step 1 — CODEBASE-FIRST (grep before you ask a person)

If a question can be answered by reading the code, read the code — do not spend a human's time on it. Use file-search/bash or spawn a subagent ("use a subagent to investigate X") to keep the main context clean. Only what the codebase cannot answer — the business intent — goes to the human.

Step 2 — GRILL (interrogate to distil)

Ask the human for structured interrogation:

• One question at a time, each with a recommended answer so the human can react fast (confirm / correct) instead of composing from scratch.
• Follow the decision tree: resolve dependencies between decisions in order; do not fan out unrelated questions.
• Quote original Japanese/English/Vietnamese when citing source requirements; translate ambiguity into plain intent (see AGENTS.md Language Handling).
• Stop as soon as the fact is pinned down — do not over-ask.

Step 3 — DISTIL (write the knowledge file)

Write one markdown file in the correct knowledge/ (kopi-cli for framework-level; the product repo for project-specific). Copy _TEMPLATE.md and fill it:

• Fact — the verified conclusion, short and checkable.
• Why — the originating decision/context (anti orphan-knowledge).
• Scope & Boundaries — applies where, and explicitly does NOT apply where.
• Sources — ClickUp/PR/Figma/person + date (auditable provenance).
• Frontmatter: copy knowledge/_TEMPLATE.md and set type, id, scope, status: active, confidence, captured_via: harvest, last_verified, verified_by, sources, related, and trace_id if it ties into an artifact chain. Preserve unknown frontmatter fields when updating existing knowledge files.

File naming: kf-<slug>.md matching the id. Cross-link related files with plain untyped markdown links (prefer bundle-absolute /file.md).

Step 4 — CONFIRM (human approves before commit)

Read the distilled Fact / Why / Scope back to the human and get explicit approval. Only after approval:

• Add a row to knowledge/INDEX.md.
• Append a line to knowledge/log.md (newest on top, ISO date).
• Stage the file (git is the version store). Do not push/merge — that follows the normal review process.

Step 5 — UPDATE (knowledge goes stale)

When a fact is wrong or outdated:

• Fix the file and bump last_verified + verified_by; or
• Set status: stale; or
• Create a new file with supersedes: <old-id> and set the old one to status: superseded.
• Reflect the change in INDEX.md and log.md. Git history records who/when/why.

Honest limits (when this is weaker than RAG)

Recall is keyword/frontmatter-based, not semantic. It is the right call while knowledge stays (1) in git and (2) at tens–hundreds of files. For a large out-of-git corpus (hundreds of JP GDocs pages, thousands of CR tickets), query the source on-demand via MCP (ClickUp/Figma/GDocs connector) and harvest the relevant part into a knowledge file — do not embed everything. If knowledge/ grows to hundreds–thousands of files and recall degrades, that is the trigger to revisit (not pre-build) a heavier search layer.

Output

• A new/updated knowledge/*.md (human-approved), with INDEX.md + log.md updated, OR
• A pointer to the existing active knowledge file that already answered the question (Step 0 short-circuit).