Skip to content
Back to search

DeepRefine-Skill

An agent skill to evolve the quality of LLM-Wiki (Graphify) at test time.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hkust-knowcomp--deeprefine-skill/badge.svg)](/listings/hkust-knowcomp--deeprefine-skill)

HTML

<a href="/listings/hkust-knowcomp--deeprefine-skill"><img src="/api/listings/hkust-knowcomp--deeprefine-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install deeprefine-cli graphifyy

cd /path/to/your-kb-project
graphify cursor install

# for Cursor
deeprefine cursor install
# for Copilot CLI
deeprefine copilot install
# for Gemini CLI
deeprefine gemini install # or deeprefine gemini link
# for Codex
deeprefine codex install
# for Claude Code
deeprefine claude install
# for OpenCode
deeprefine opencode install

After upgrading the package, run the command again to refresh local skill files.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 421 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: deeprefine
  3. description: >-
  4. Agent-native DeepRefine refinement loop — same control flow as DeepRefine.refine(),
  5. graphify search instead of FAISS, session LLM, dry-run review before approved graph writes.
  6. disable-model-invocation: false
  7. ---
  8. # DeepRefine — Agent refinement loop (strict)
  9. ## Default safety policy: dry-run only
  10. A normal `/deeprefine` invocation **MUST NEVER** call `deeprefine apply`.
  11. The default `/deeprefine` workflow must stop after:
  12. 1. `deeprefine loop validate`
  13. 2. `deeprefine review`
  14. 3. showing the proposed actions and HIGH/MEDIUM/LOW review report to the user
  15. Then ask the user for explicit approval.
  16. Only if the user's **next message** explicitly says to approve/apply/write the graph may you run:
  17. ```bash
  18. deeprefine apply --refresh-wiki --trace-file ... --refinement-file ...
  19. deeprefine loop finish --trace-file ... --refinement-file ...
  20. ```
  21. Do not treat generation of `<refinement>` actions as approval. Do not treat a valid trace as approval. Do not apply in the same `/deeprefine` turn.
  22. ---
  23. You **MUST** implement the **same control flow** as `DeepRefine.refine()` in DeepRefine (`autorefiner/src/deeprefine.py`).
  24. | Component | Agent mode | CLI `deeprefine refine` |
  25. |-----------|------------|-------------------------|
  26. | Retrieval | `graphify query` + k-hop from `graph.json` | FAISS retriever |
  27. | LLM | **Your session model** | External API / vLLM |
  28. | Graph writes | Dry-run proposal + `deeprefine review`; `deeprefine apply` only after user approval | Dry-run by default; `--apply` persists |
  29. ---
  30. ## FORBIDDEN (hard stop)
  31. Do **NOT**:
  32. 1. Run `deeprefine refine` (unless the user explicitly asks for CLI/FAISS mode).
  33. 2. Call `deeprefine apply` without a valid `loop_trace_<query_id>.json` (CLI will reject).
  34. 3. Call `deeprefine apply` before running `deeprefine review` and receiving explicit user approval.
  35. 4. Ignore LOW-confidence review warnings unless the user explicitly requests `--allow-low-confidence`.
  36. 5. Skip any hop’s `<judge>Yes</judge>` / `<judge>No</judge>` judgement.
  37. 6. Skip error abduction when `len(interaction_history) > 1`.
  38. 7. Write `<refinement>` before abduction when refinement is required.
  39. 8. Hand-edit `graph.json` with Python or ad-hoc JSON patches.
  40. 9. Ignore pending history and refine only one latest query when unrefined queries already exist.
  41. 10. Invent a shorter pipeline (“read file → write refinement → apply”).
  42. If validation fails, **fix the trace and re-run the missing step** — do not bypass with `--skip-trace-check`.
  43. ---
  44. ## Constants (match `refine_runner.py` / DeepRefine)
  45. ```text
  46. MAX_HOPS = 4
  47. INCREMENT_HOP = 1
  48. BASE_TOP_K = 10
  49. MAX_TRIPLE_NUM_BY_STEP = [5, 10, 15, 20] # cap triples per step
  50. HISTORY_HORIZON = 4 # abduction uses last N steps
  51. ```
  52. ---
  53. ## Mandatory artifact
  54. For each query, maintain:
  55. `graphify-out/.deeprefine/loop_trace_<query_id>.json`
  56. Create template:
  57. ```bash
  58. deeprefine loop init --query "<exact question>"
  59. ```
  60. Append each hop to `interaction_history` **before** starting the next hop.
  61. Run `deeprefine loop validate --trace-file ...` after abduction and before `review` / approved `apply`.
  62. ---
  63. ## Query queue selection (default behavior of `/deeprefine`)
  64. `/deeprefine` must process **all unrefined history queries** first, not just the latest one.
  65. 1. Sync graphify query memory into DeepRefine history:
  66. - run: `deeprefine history sync-memory`
  67. - source dir: `graphify-out/memory/query_*.md`
  68. - target file: `graphify-out/.deeprefine/history.jsonl`
  69. 2. Read pending queue from `graphify-out/.deeprefine/history.jsonl`:
  70. - include rows where `refined != true`
  71. - dedupe by `id` (first occurrence)
  72. - preserve file order
  73. 3. If pending queue is non-empty: set `target_queries = pending_queue`.
  74. 4. If pending queue is empty: set `target_queries = [current session question]`.
  75. 5. Run the full refinement loop for **each** query in `target_queries`, one by one.
  76. 6. For early-exit queries, finish immediately. For refinement-path queries, generate review output and wait for user approval before `apply` + `loop finish`.
  77. ---
  78. ## Control flow (must match `DeepRefine.refine()`)
  79. Pseudocode — follow **exactly**:
  80. ```text
  81. target_queries = pending_history_queries() # refined != true, dedupe by id, keep order
  82. run "deeprefine history sync-memory" before loading pending history
  83. if target_queries is empty:
  84. target_queries = [current session question]
  85. for question in target_queries:
  86. interaction_history = []
  87. for step in 1..MAX_HOPS:
  88. print "[Step: {step}]" # show in chat
  89. if step == 1:
  90. # Vector-retrieval equivalent: graphify query on full question
  91. RUN: graphify query "<question>"
  92. triples = parse NODE/EDGE → [{subject, relation, object}, ...]
  93. cap = MAX_TRIPLE_NUM_BY_STEP[0] # 5
  94. record retrieval.method = "graphify_query"
  95. else:
  96. # k-hop expansion from entities in previous hop (NOT a new random search)
  97. entities = unique subjects/objects from previous triples
  98. expand 1-hop neighbors from graphify-out/graph.json (or graphify query on entities)
  99. cap = MAX_TRIPLE_NUM_BY_STEP[step-1]
  100. record retrieval.method = "k_hop_expansion" or "graphify_query+k_hop_expansion"
  101. triples = dedupe; len(triples) <= cap
  102. # Answerable judgement — session LLM, prompts below
  103. answerable, judgement_raw = LLM_judge(question, triples)
  104. MUST output ONLY: <judge>Yes</judge> or <judge>No</judge>
  105. append interaction_history with:
  106. step, query, num_hops=(step-1)*INCREMENT_HOP, base_top_k=10,
  107. retrieved_subgraph, answerable, judgement_raw,
  108. retrieval: {method, evidence: "<command output excerpt>"}
  109. if answerable:
  110. BREAK # stop hop loop
  111. # --- same branch as DeepRefine.refine() line 314+ ---
  112. if len(interaction_history) <= 1:
  113. # Early exit: first hop was answerable — NO graph refinement
  114. set trace.early_exit = true
  115. deeprefine loop finish --trace-file ... # no --refinement-file
  116. CONTINUE # move to next pending query
  117. else:
  118. # len > 1 → ALWAYS error abduction + actions (even if last hop was Yes)
  119. error_abduction = LLM_abduction(interaction_history[-HISTORY_HORIZON:])
  120. MUST output: <abduction>...</abduction>
  121. actions = LLM_kg_refinement(
  122. last_hop.retrieved_subgraph,
  123. error_abduction,
  124. question,
  125. source file hints from triples,
  126. )
  127. MUST output: <refinement>insert_edge(...)|...</refinement>
  128. save refinement to graphify-out/.deeprefine/refinement_actions_<id>.txt
  129. deeprefine loop validate --trace-file ... --refinement-file ...
  130. deeprefine review --trace-file ... --refinement-file ...
  131. SHOW review labels: HIGH / MEDIUM / LOW, evidence, warnings, suggested replacements
  132. HARD STOP: do not modify graph.json in this /deeprefine turn
  133. Report the proposed actions and HIGH/MEDIUM/LOW review to the user
  134. Ask for explicit approval; approval must arrive in the user's next message
  135. # Follow-up turn only, after the user's next message explicitly approves/apply/write:
  136. if user explicitly approves and no LOW-confidence action remains:
  137. deeprefine apply --refresh-wiki --trace-file ... --refinement-file ...
  138. deeprefine loop finish --trace-file ... --refinement-file ...
  139. if user explicitly accepts LOW-confidence risk in that approval message:
  140. deeprefine apply --refresh-wiki --allow-low-confidence --trace-file ... --refinement-file ...
  141. deeprefine loop finish --trace-file ... --refinement-file ...
  142. ```
  143. **Critical refinement rule:** refinement runs when `len(interaction_history) > 1`, not only when all judgements are `No`.
  144. **Safe-review rule:** a refinement path is dry-run by default. Generating `<refinement>` actions is not approval to write `graph.json`, and a normal `/deeprefine` turn must end after `deeprefine review`.
  145. ---
  146. ## Evidence-aware review rules
  147. Before any graph write, run:
  148. ```bash
  149. deeprefine review --trace-file graphify-out/.deeprefine/loop_trace_<id>.json --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
  150. ```
  151. The review must label every action:
  152. - `HIGH`: direct graph or code evidence exists.
  153. - `MEDIUM`: k-hop context supports the action, but direct code or exact-edge evidence is missing.
  154. - `LOW`: endpoint nodes are ambiguous, too broad, cross-community, or cannot be grounded in `graph.json`.
  155. Bare names such as `main()`, `run()`, `train()`, `test()`, and `setup()` are ambiguous even if they match only one node. Prefer file-qualified labels such as `trainer_Brain_CLS.py::train_epoch()`.
  156. `deeprefine apply` refuses LOW-confidence actions by default. Use `--allow-low-confidence` only when the user explicitly approves the risk.
  157. ---
  158. ## LLM prompts (verbatim — do not paraphrase)
  159. ### Judgement (`_answerable_judgement`)
  160. **System:**
  161. ```text
  162. As an advanced judgement assistant, your task is to judge whether the given question is answerable based on the provided KG context.
  163. Evaluate whether the given question is answerable based on the provided KG context. Output your judgment in the following format:
  164. <judge>Yes</judge> or <judge>No</judge>
  165. **Important:** You must think carefully about the question and the KG context before making your judgment. And output your judgment result directly in the specified format.
  166. ```
  167. **User:**
  168. ```text
  169. Question: {question}
  170. Knowledge Graph (KG) context: {triples_string}
  171. ```
  172. `{triples_string}` = one triple per line: `subject | relation | object`
  173. ### Error abduction (`_error_abduction`) — only if `len(interaction_history) > 1`
  174. **System:**
  175. ```text
  176. As an advanced error abduction assistant, your task is to analyze the error reasons based on the given interaction history.
  177. Analyze the reasons of the unanswerable questions based on the given interaction history from the incompleteness, incorrectness, and redundancy perspectives. Output your analysis in the following format:
  178. <abduction>...</abduction>
  179. **Important:** You must think carefully about the interaction history before making your analysis. And output your analysis result directly in the specified format.
  180. ```
  181. **User:**
  182. ```text
  183. Interaction history: {interaction_history}
  184. ```
  185. `{interaction_history}` format (same as DeepRefine):
  186. ```text
  187. Step1:
  188. ['Query': ..., 'Subgraph_hop': ..., 'Subgraph_content': ..., 'Answerable': ...]
  189. Step2:
  190. ...
  191. ```
  192. ### KG refinement actions (`_kg_refinement_action`) — only if `len(interaction_history) > 1`
  193. **System:**
  194. ```text
  195. As an advanced knowledge graph refinement assistant, your task is to generate a series of actions (**within 10 actions**) to refine the given KG to make it more suitable for answering the given question.
  196. Based on the given KG and the analysed error reasons, refine the given KG to make it more easily for retrieval and answering the given question. You have the following three types of actions to conduct:
  197. - insert_edge(subject, relation, object): Insert a new edge into the KG to complete the missing information.
  198. - delete_edge(subject, relation, object): Delete an edge from the KG to remove the redundant information or conflicting information.
  199. - replace_node(old_entity, new_entity): Replace an entity in the KG to correct the errors or deal with disambiguation.
  200. Output a series of actions (**within 10 actions**) in the following format:
  201. <refinement>insert_edge("...", "...", "...")|delete_edge("...", "...", "...")|replace_node("...", "...")|...</refinement>
  202. **Important:** You must think carefully about the given KG and the analysed error reasons before making your refinement. DO NOT DELETE ANY IRRELEVANT TRIPLES FROM THE ORIGINAL KG. TRY TO KEEP THE ORIGINAL KG AS MUCH AS POSSIBLE. DO NOT GENERATE TOO MANY ACTIONS. And output your refinement result directly in the specified format.
  203. ```
  204. **User:**
  205. ```text
  206. Original Text: {original_text}
  207. KG: {triples_string}
  208. Question: {question}
  209. Error reasons: {error_reasons}
  210. ```
  211. Use **last hop’s** `retrieved_subgraph` as `{triples_string}` (JSON list is OK in trace; string form for the prompt).
  212. ---
  213. ## Per-query checklist (report in chat)
  214. Copy and tick each item in your final message:
  215. ```text
  216. [ ] Backup: graphify-out/.deeprefine/graph.json.bak
  217. [ ] loop_trace_<id>.json created
  218. [ ] Step 1: graphify query executed (evidence in trace)
  219. [ ] Each step: <judge>Yes|No</judge> shown in chat
  220. [ ] Hops stopped on Yes OR reached MAX_HOPS
  221. [ ] early_exit OR (abduction + refinement) per DeepRefine branch
  222. [ ] deeprefine loop validate passed
  223. [ ] deeprefine review generated with HIGH/MEDIUM/LOW labels
  224. [ ] graph.json intentionally left unchanged pending next-message approval OR user approved in a follow-up message
  225. [ ] deeprefine apply skipped in normal /deeprefine turn; only run after next-message approval
  226. [ ] deeprefine loop finish
  227. ```
  228. ---
  229. ## Commands (in order)
  230. ```bash
  231. # 0. KB project root; graphify-out/graph.json exists
  232. mkdir -p graphify-out/.deeprefine
  233. cp graphify-out/graph.json graphify-out/.deeprefine/graph.json.bak
  234. # 1. Sync graphify query memory to deeprefine history first.
  235. deeprefine history sync-memory
  236. # 2. Build target query list:
  237. # - preferred: all pending from history.jsonl (refined != true)
  238. # - fallback: current session question (single query)
  239. deeprefine history list --pending
  240. # 3. For EACH query in target list:
  241. deeprefine loop init --query "<question>"
  242. # 4–7. For each hop: graphify/graph read → judge → append to loop_trace_*.json
  243. # 8a. Early exit (len(history)==1 and answerable)
  244. deeprefine loop validate --trace-file graphify-out/.deeprefine/loop_trace_<id>.json
  245. deeprefine loop finish --trace-file graphify-out/.deeprefine/loop_trace_<id>.json
  246. # 8b. Refinement path (len(history)>1): dry-run review first
  247. deeprefine loop validate --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
  248. deeprefine review --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
  249. # HARD STOP.
  250. # A normal /deeprefine run must end here.
  251. # Report the review to the user and ask for explicit approval.
  252. # Do NOT run deeprefine apply in the same /deeprefine turn.
  253. # Approval-only follow-up commands, only after the user explicitly says approve/apply:
  254. deeprefine apply --refresh-wiki --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
  255. # Optional explicit risk override:
  256. # deeprefine apply --refresh-wiki --allow-low-confidence --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
  257. deeprefine loop finish --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
  258. # 9. Repeat step 3..8 until all pending queries are reviewed/finished.
  259. ```
  260. ---
  261. ## `loop_trace_*.json` schema
  262. ```json
  263. {
  264. "schema_version": 1,
  265. "mode": "agent-loop",
  266. "query": "what is dulce?",
  267. "query_id": "5cdc0798eb59b486",
  268. "constants": { "max_hops": 4, "increment_hop": 1, "base_top_k": 10,
  269. "max_triple_num_by_step": [5, 10, 15, 20], "history_horizon_size": 4 },
  270. "interaction_history": [
  271. {
  272. "step": 1,
  273. "num_hops": 0,
  274. "base_top_k": 10,
  275. "query": "what is dulce?",
  276. "retrieval": {
  277. "method": "graphify_query",
  278. "evidence": "graphify query \"what is dulce?\" → …"
  279. },
  280. "retrieved_subgraph": [
  281. {"subject": "A", "relation": "r", "object": "B"}
  282. ],
  283. "answerable": false,
  284. "judgement_raw": "<judge>No</judge>"
  285. }
  286. ],
  287. "error_abduction_reason": "…",
  288. "error_abduction_raw": "<abduction>…</abduction>",
  289. "refinement_action_file": "graphify-out/.deeprefine/refinement_actions_<id>.txt",
  290. "early_exit": false
  291. }
  292. ```
  293. ---
  294. ## Optional: CLI mode (FAISS + API)
  295. Only when the user **explicitly** requests `deeprefine refine` / full runtime:
  296. ```bash
  297. conda activate atlastune
  298. export DEEPREFINE_EMBED_URL=... DEEPREFINE_LLM_URL=...
  299. deeprefine refine --query "..." # dry-run proposal only
  300. # deeprefine refine --query "..." --apply # only when the user explicitly wants CLI mode to write graph.json
  301. ```
  302. ---
  303. ## Paths
  304. - `graphify-out/graph.json`
  305. - `graphify-out/.deeprefine/loop_trace_*.json` (**required**)
  306. - `graphify-out/.deeprefine/refinement_actions_*.txt`
  307. - `graphify-out/.deeprefine/refinement_results_*.jsonl`
  308. - `graphify-out/.deeprefine/proposed_refinement_review_*.md`
  309. - `graphify-out/.deeprefine/proposed_refinement_review_*.json`
  310. - `graphify-out/.deeprefine/graph.json.bak`
README.md · README · 576 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # DeepRefine-Skill
  3. <table style="border: none; margin: 0 auto; padding: 0; border-collapse: collapse;">
  4. <tr>
  5. <td align="center" style="vertical-align: middle; padding: 10px; border: none; width: 250px;">
  6. <img src="./assets/icons3.png" alt="DeepRefine Logo" width="200" style="margin: 0; padding: 0; display: block;"/>
  7. </td>
  8. <td align="left" style="vertical-align: middle; padding: 10px 0 10px 30px; border: none;">
  9. <pre style="font-family: 'Courier New', monospace; font-size: 16px; color: #0EA5E9; margin: 0; padding: 0; text-shadow: 0 0 10px #0EA5E9, 0 0 20px rgba(14,165,233,0.5); line-height: 1.2; transform: skew(-1deg, 0deg); display: block;">██████╗ ███████╗███████╗██████╗ ██████╗ ███████╗███████╗██╗███╗ ██╗███████╗
  10. ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝██║████╗ ██║██╔════╝
  11. ██║ ██║█████╗ █████╗ ██████╔╝██████╔╝█████╗ █████╗ ██║██╔██╗ ██║█████╗
  12. ██║ ██║██╔══╝ ██╔══╝ ██╔═══╝ ██╔══██╗██╔══╝ ██╔══╝ ██║██║╚██╗██║██╔══╝
  13. ██████╔╝███████╗███████╗██║ ██║ ██║███████╗██║ ██║██║ ╚████║███████╗
  14. ╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝</pre>
  15. </td>
  16. </tr>
  17. </table>
  18. [![PyPi](https://img.shields.io/badge/PyPi-v0.2.0-blue.svg)](https://pypi.org/project/deeprefine-cli/0.2.0/)
  19. [![Python](https://img.shields.io/badge/Python-3.10,3.11,3.12-blue.svg)](https://pypi.org/project/deeprefine-cli/0.2.0/)
  20. [![Paper](https://img.shields.io/badge/Paper-DeepRefine-b31b1b.svg)](https://arxiv.org/pdf/2605.10488)
  21. [![Project](https://img.shields.io/badge/Project-DeepRefine-green.svg)](https://github.com/HKUST-KnowComp/DeepRefine)
  22. </div>
  23. DeepRefine-Skill plugs into agent workflows and use a single command `/deeprefine` in your agent (Cursor, Copilot CLI, Gemini CLI, Codex, OpenCode, Claude Code) to refine and evolve your LLM-Wiki (e.g., **[graphify](https://github.com/safishamsi/graphify)**) knowledge base.
  24. <p align="center">
  25. <img src="assets/demo-typing-deeprefine.svg" alt="Demo: /deeprefine" />
  26. </p>
  27. It refines your graphify knowledge graph for better future retrieval and Q&A quality.
  28. Supported agent frameworks:
  29. <p>
  30. <a href="https://cursor.com" title="Cursor"><img src="./assets/cursor_CUBE_25D.png" alt="Cursor" height="40"/></a>&nbsp;&nbsp;
  31. <a href="https://github.com/google-gemini/gemini-cli" title="Gemini CLI"><img src="./assets/gemini-cli-icon_full-color@4x.png" alt="Gemini CLI" height="40"/></a>&nbsp;&nbsp;
  32. <a href="https://docs.github.com/en/copilot" title="GitHub Copilot CLI" style="text-decoration: none; color: inherit;"><img src="./assets/github-copilot__1_-removebg-preview.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>&nbsp;&nbsp;
  33. <a href="https://openai.com/codex/" title="Codex CLI" style="text-decoration: none; color: inherit;"><img src="./assets/codex-color.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>&nbsp;&nbsp;
  34. <a href="https://opencode.ai/" title="OpenCode" style="text-decoration: none; color: inherit;"><img src="./assets/opencode-logo-dark.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>&nbsp;&nbsp;
  35. <a href="https://claude.com/product/claude-code" title="Claude Code" style="text-decoration: none; color: inherit;"><img src="./assets/claudecode-color.png" height="40" style="vertical-align: middle;" alt="Copilot Icon" /></a>&nbsp;&nbsp;
  36. </p>
  37. ---
  38. ## News
  39. - **[2026/7/10] v0.2.0** - Claude Code and OpenCode adapters: `deeprefine claude install` / `deeprefine opencode install`, bundled skill + command templates.
  40. - **[2026/7/3] v0.1.9** - Release with Codex, Copilot CLI, and Gemini CLI skills bundled; dry-run-first refinement, evidence-aware action review (HIGH/MEDIUM/LOW), ambiguous-node warnings, and LOW-confidence apply guard.
  41. - **[2026/6/24] v0.1.9** - Codex skill supported.
  42. - **[2026/6/18] v0.1.9** - Gemini CLI and Copilot CLI supported.
  43. - **[2026/6/17] v0.1.9** - Added dry-run-first refinement, evidence-aware action review, ambiguous-node warnings, and LOW-confidence apply guard.
  44. - **[2026/6/15] v0.1.8** - Aligned interaction memory with LLM-Wiki (graphify) and fixed the single query refinement issue.
  45. - **[2026/6/2] v0.1.7** — Cursor skill + `deeprefine refine` with configurable API. And strict DeepRefine agent loop.
  46. ## Agent CLI (Recommended)
  47. This is the default mode and the main workflow for this project.
  48. ### One-time setup
  49. ```bash
  50. pip install deeprefine-cli graphifyy
  51. cd /path/to/your-kb-project
  52. graphify cursor install
  53. # for Cursor
  54. deeprefine cursor install
  55. # for Copilot CLI
  56. deeprefine copilot install
  57. # for Gemini CLI
  58. deeprefine gemini install # or deeprefine gemini link
  59. # for Codex
  60. deeprefine codex install
  61. # for Claude Code
  62. deeprefine claude install
  63. # for OpenCode
  64. deeprefine opencode install
  65. ```
  66. After upgrading the package, run the command again to refresh local skill files.
  67. ### Typical session (Agent CLI)
  68. ```bash
  69. /graphify .
  70. /graphify ./ --wiki
  71. /graphify query "your question 1"
  72. /graphify query "your question 2"
  73. # ..
  74. /deeprefine
  75. ```
  76. ### What `/deeprefine` does now (default queue behavior)
  77. <details>
  78. <summary><strong>Procedures:</strong></summary>
  79. When you run `/deeprefine`, it should follow this order:
  80. 1. `deeprefine history sync-memory`
  81. - import queries from `graphify-out/memory/query_*.md`
  82. - write to `graphify-out/.deeprefine/history.jsonl`
  83. 2. load pending queries from `history.jsonl` (`refined != true`)
  84. 3. refine pending queries sequentially
  85. 4. for refinement-path queries, generate `<refinement>` actions and run `deeprefine review`
  86. 5. stop in dry-run mode and show the review report; do **not** modify `graph.json` yet
  87. 6. only after user approval, run `deeprefine apply --refresh-wiki` and then `deeprefine loop finish`
  88. </details>
  89. ### Agent artifacts
  90. ```text
  91. graphify-out/
  92. ├── graph.json # graphify main graph; unchanged until apply approval
  93. ├── memory/
  94. │ └── query_*.md # graphify query logs (sync source)
  95. └── .deeprefine/
  96. ├── history.jsonl # DeepRefine-maintained history queue
  97. ├── graph.json.bak # backup before first apply in this run
  98. ├── checkpoints/graph.checkpoint.<seq>.json # post-state graph after each apply
  99. ├── checkpoints.json # checkpoint timeline registry
  100. ├── loop_trace_<query_id>.json # per-query loop audit trace
  101. ├── refinement_results_<YYYYMMDD>.jsonl # per-day run log
  102. ├── refinement_actions_*.txt # optional; only when refinement path is taken
  103. ├── proposed_refinement_actions_*.txt # CLI dry-run proposed actions
  104. ├── proposed_refinement_review_*.md # evidence-aware review report
  105. └── proposed_refinement_review_*.json # optional structured review report
  106. ```
  107. ### Agent-related commands
  108. Run from your KB project root.
  109. | Command | Description |
  110. |---------|-------------|
  111. | `deeprefine cursor install` | Install `/deeprefine` skill for Cursor (`.cursor/skills/deeprefine/`) |
  112. | `deeprefine cursor install --user` | Install Cursor skill for all projects (`~/.cursor/skills/`) |
  113. | `deeprefine copilot install` | Install `/deeprefine` skill for Copilot CLI (`.github/skills/deeprefine/`) |
  114. | `deeprefine copilot install --user` | Install Copilot CLI skill for all projects (`~/.copilot/skills/`) |
  115. | `deeprefine copilot uninstall` | Remove Copilot CLI skill |
  116. | `deeprefine codex install` | Install `$deeprefine` skill for Codex (`.agents/skills/deeprefine/`) |
  117. | `deeprefine codex install --user` | Install Codex skill for all projects (`~/.codex/skills/deeprefine/`) |
  118. | `deeprefine codex uninstall` | Remove Codex skill |
  119. | `deeprefine claude install` | Install `/deeprefine` skill for Claude Code (`.claude/skills/deeprefine/`) |
  120. | `deeprefine claude install --user` | Install Claude Code skill for all projects (`~/.claude/skills/deeprefine/`) |
  121. | `deeprefine claude uninstall` | Remove the Claude Code skill |
  122. | `deeprefine opencode install` | Install `/deeprefine` skill + commands for OpenCode (`.opencode/`) |
  123. | `deeprefine opencode install --user` | Install OpenCode skill for all projects (`~/.opencode/`) |
  124. | `deeprefine opencode uninstall` | Remove the OpenCode skill and commands |
  125. | `deeprefine gemini path` | Print the extension root used for Gemini CLI |
  126. | `deeprefine gemini link` | Link the current source checkout with `gemini extensions link` |
  127. | `deeprefine gemini install` | Install the bundled extension with `gemini extensions install` |
  128. | `deeprefine gemini install --copy-only` | Manual fallback copy to `~/.gemini/extensions/deeprefine-skill` |
  129. | `deeprefine gemini uninstall` | Remove the extension with Gemini CLI's manager |
  130. | `deeprefine history sync-memory` | Import `graphify-out/memory/query_*.md` into DeepRefine history |
  131. | `deeprefine history list --pending` | Show unrefined queue |
  132. | `deeprefine loop init --query "..."` | Create `loop_trace_<id>.json` template |
  133. | `deeprefine loop validate --trace-file T` | Validate trace against DeepRefine control flow |
  134. | `deeprefine review --trace-file T --refinement-file F` | Review proposed actions with HIGH/MEDIUM/LOW evidence labels; no graph write |
  135. | `deeprefine apply --refresh-wiki --trace-file T --refinement-file F` | Apply actions and regenerate `graphify-out/wiki` from the refined graph; graph + Wiki are committed together |
  136. | `deeprefine apply --refresh-wiki --allow-low-confidence --trace-file T --refinement-file F` | Refresh the Wiki while explicitly overriding the LOW-confidence guard |
  137. | `deeprefine loop finish --trace-file T [--refinement-file F]` | Persist results and mark history refined |
  138. ### Evidence-aware review and safe apply
  139. `/deeprefine` should default to dry-run-first behavior. Proposed actions are reviewed before they can modify `graphify-out/graph.json`. Each action is labeled:
  140. | Label | Meaning |
  141. |-------|---------|
  142. | `HIGH` | Direct graph or code evidence exists. |
  143. | `MEDIUM` | k-hop context supports the action, but direct code or exact-edge evidence is missing. |
  144. | `LOW` | Node names are ambiguous, too broad, cross-community, or cannot be grounded in `graph.json`. |
  145. Bare function names such as `main()`, `run()`, `train()`, `test()`, and `setup()` are treated as ambiguous. Prefer file-qualified names:
  146. ```text
  147. BAD: insert_edge("main()", "calls", "Trainer")
  148. GOOD: insert_edge("pretraining/pretraining_CLIP_fine-grained.py::main()", "calls", "Trainer")
  149. ```
  150. `deeprefine apply` refuses LOW-confidence actions by default. Use `--allow-low-confidence` only when the user explicitly accepts the risk.
  151. When the knowledge base was created with Graphify Wiki output, use `--refresh-wiki`. DeepRefine stages the refined graph, regenerates the Wiki with `graphify export wiki`, validates `wiki/index.md`, and only then replaces the production graph and Wiki. If export fails, the existing graph and Wiki remain unchanged.
  152. ---
  153. ## Codex Integration
  154. <details>
  155. <summary><strong>Setup, commands, and session usage</strong></summary>
  156. DeepRefine works as a Codex skill. The installer writes the Codex-specific
  157. skill file to `.agents/skills/deeprefine/SKILL.md` and UI metadata to
  158. `.agents/skills/deeprefine/agents/openai.yaml`. It also installs focused
  159. references under `.agents/skills/deeprefine/references/` for the refinement
  160. workflow, LLM prompts, and trace/command details.
  161. ### One-time setup
  162. ```bash
  163. cd /path/to/your-kb-project
  164. pip install deeprefine-cli
  165. deeprefine codex install --project
  166. ```
  167. After upgrading the package, run `deeprefine codex install --project` again to
  168. refresh the local skill files. Restart or reload Codex, then invoke:
  169. ```text
  170. $deeprefine
  171. /deeprefine
  172. ```
  173. ### Codex commands
  174. | Command | Description |
  175. |---------|-------------|
  176. | `deeprefine codex install` | Install the Codex skill into `.agents/skills/deeprefine/` |
  177. | `deeprefine codex install --user` | Install the Codex skill into `~/.codex/skills/deeprefine/` |
  178. | `deeprefine codex uninstall` | Remove the Codex skill |
  179. ### Codex session
  180. ```text
  181. $deeprefine
  182. ```
  183. Codex runs the full agent-native refinement loop for pending queries, stops after
  184. `deeprefine review`, and presents the HIGH/MEDIUM/LOW report. Reply with an
  185. explicit apply/approve message only after reviewing the proposed actions.
  186. See [`docs/codex.md`](docs/codex.md) for details.
  187. </details>
  188. ---
  189. ## Copilot CLI Integration
  190. <details>
  191. <summary><strong>Setup, commands, and session usage</strong></summary>
  192. DeepRefine works as a GitHub Copilot CLI agent skill. The skill file is
  193. installed into `.github/skills/deeprefine/SKILL.md` and auto-discovered by
  194. Copilot. Shell commands are pre-approved via `allowed-tools: shell`.
  195. ### One-time setup
  196. ```bash
  197. cd /path/to/your-kb-project
  198. pip install deeprefine-cli
  199. deeprefine copilot install --project
  200. ```
  201. After upgrading the package, run `deeprefine copilot install --project` again
  202. to refresh the local skill file. Start a Copilot CLI session and reload:
  203. ```text
  204. /skills reload
  205. /skills info deeprefine
  206. ```
  207. ### Mode detection
  208. Copilot CLI does not natively support sub-commands, so the skill uses
  209. keyword-based mode detection in the SKILL.md preamble:
  210. | Mode | Trigger keywords | Behavior |
  211. |------|-----------------|----------|
  212. | **Full workflow** | `/deeprefine`, "refine", "improve", "fix" | Full refinement loop; stops after dry-run review; asks for approval |
  213. | **Review only** | "review", "check", "audit", "inspect", "dry-run" | Reads trace + refinement file; shows HIGH/MEDIUM/LOW report; no graph writes |
  214. | **Apply only** | "approve", "apply", "write", "go ahead" | Runs `deeprefine apply` only after a prior review; requires explicit user approval in the current message |
  215. ### Copilot CLI session
  216. ```text
  217. /deeprefine
  218. ```
  219. The agent runs the full refinement loop for all pending queries. For
  220. refinement-path queries, it stops after the dry-run review and asks:
  221. ```text
  222. [HIGH] insert_edge("trainer.py::train_epoch()", "calls", "validate()")
  223. Evidence: Direct code evidence in trainer.py.
  224. [MEDIUM] insert_edge("data.py::load()", "imports", "torch")
  225. Warning: No direct code evidence found.
  226. Apply only after review. Approve?
  227. ```
  228. Reply "apply" or "go ahead" to proceed; the agent will run
  229. `deeprefine apply` in the follow-up turn.
  230. </details>
  231. ---
  232. ## Gemini CLI Integration
  233. <details>
  234. <summary><strong>Setup, commands, and session usage</strong></summary>
  235. DeepRefine can also be used as a Gemini CLI extension. This keeps the same safe,
  236. dry-run-first DeepRefine workflow while making `/deeprefine` available inside
  237. Gemini CLI.
  238. ### One-time setup for local development
  239. ```bash
  240. cd /path/to/DeepRefine-Skill
  241. pip install -e .
  242. deeprefine gemini link
  243. ```
  244. `deeprefine gemini link` calls Gemini CLI's official extension manager:
  245. ```bash
  246. gemini extensions link /path/to/DeepRefine-Skill
  247. ```
  248. Restart Gemini CLI after linking. Then check:
  249. ```text
  250. /extensions list
  251. /commands list
  252. ```
  253. Expected commands:
  254. ```text
  255. /deeprefine
  256. /deeprefine:review
  257. /deeprefine:apply
  258. ```
  259. ### Gemini CLI commands
  260. | Command | Description |
  261. |---------|-------------|
  262. | `deeprefine gemini path` | Print the extension root used for Gemini CLI |
  263. | `deeprefine gemini link` | Link the current source checkout with `gemini extensions link` |
  264. | `deeprefine gemini install` | Install the bundled extension with `gemini extensions install` |
  265. | `deeprefine gemini install --copy-only` | Manual fallback copy to `~/.gemini/extensions/deeprefine-skill` |
  266. | `deeprefine gemini uninstall` | Remove the extension with Gemini CLI's manager |
  267. For normal source development, prefer `deeprefine gemini link`. It makes the
  268. extension visible to `/extensions list`, whereas copying files alone may not
  269. register the extension in newer Gemini CLI versions.
  270. ### Gemini CLI session
  271. ```bash
  272. gemini
  273. ```
  274. Then run:
  275. ```text
  276. /deeprefine
  277. /deeprefine:review "Why is the graph missing the data loading path?"
  278. /deeprefine:apply "Apply the approved refinement actions from the valid trace."
  279. ```
  280. The extension files are located at the repository root and are also bundled under
  281. `deeprefine_skill/gemini_extension/` for wheel installs. See
  282. [`docs/gemini-cli.md`](docs/gemini-cli.md) for details.
  283. </details>
  284. ## OpenCode Integration
  285. <details>
  286. <summary><strong>Setup, commands, and session usage</strong></summary>
  287. ### Prerequisites
  288. - **OpenCode CLI** installed and configured
  289. - **graphify** CLI available on your PATH
  290. - **Python 3.10+** with `deeprefine-cli` installed
  291. - A `graphify-out/graph.json` knowledge graph in your project
  292. ### Setup
  293. ```bash
  294. # Install into the current project
  295. deeprefine opencode install --project
  296. # Install globally (all projects)
  297. deeprefine opencode install --user
  298. ```
  299. This installs **4 files**:
  300. | Destination | Source | Purpose |
  301. |------------|--------|---------|
  302. | `.opencode/skills/deeprefine/SKILL.md` | `SKILL_OPENCODE.md` | Agent harness with 6 OpenCode-native optimizations |
  303. | `.opencode/commands/deeprefine.md` | `commands/opencode/deeprefine.md` | Full workflow entrypoint (`/deeprefine`) |
  304. | `.opencode/commands/deeprefine-review.md` | `commands/opencode/deeprefine-review.md` | Review-only entrypoint (`/deeprefine-review`) |
  305. | `.opencode/commands/deeprefine-apply.md` | `commands/opencode/deeprefine-apply.md` | Apply-only entrypoint (`/deeprefine-apply`) |
  306. ### Commands
  307. | Command | Description |
  308. |---------|-------------|
  309. | `/deeprefine` | Full pipeline: sync → judge → abduction → refinement → 5-Oracle review → (await approval) → apply → post-apply verify |
  310. | `/deeprefine-review` | Review only: read existing actions → 5-Oracle audit → evidence review → present results |
  311. | `/deeprefine-apply` | Apply only: read reviewed actions → confirm → apply → post-apply verify → finish |
  312. ### Model Configuration
  313. OpenCode supports per-phase model routing via environment variables:
  314. | Variable | Phase | Purpose |
  315. |----------|-------|---------|
  316. | `DEEPREFINE_JUDGE_MODEL` | Judgement (`<judge>Yes/No</judge>`) | Fast, cheap model for binary classification (e.g., `gpt-4o-mini`) |
  317. | `DEEPREFINE_REFINE_MODEL` | Abduction + Refinement | Strong reasoning model for complex causal analysis (e.g., `claude-sonnet-4-20250514`) |
  318. If either variable is unset, the session default model is used.
  319. ### OpenCode-Native Optimizations
  320. DeepRefine on OpenCode includes 6 platform-native optimizations not available in Cursor or Cline:
  321. 1. **Parallel query processing** — Multiple pending queries are dispatched to parallel subagents via `task()`, reducing wall-clock time to ~1 query's duration
  322. 2. **Phase-specific model routing** — Binary judgement uses a cheap model; complex abduction/refinement uses a strong model
  323. 3. **Structured progress tracking** — `todowrite()` replaces text checklists, enabling real-time progress visibility and cross-session resumption
  324. 4. **5-Oracle parallel review** — Five specialized oracle subagents audit refinement actions from orthogonal angles (completeness, correctness, safety, consistency, edge-cases) before any graph mutation
  325. 5. **Post-apply auto-verification** — After applying refinement actions, the original query is re-run to confirm the graph fix actually resolved the issue
  326. 6. **Evidence ledger** — Every phase boundary writes a structured JSONL entry (`graphify-out/.deeprefine/ledger.jsonl`) with timestamps, artifacts, and QA results for full auditability
  327. ### Uninstall
  328. ```bash
  329. deeprefine opencode uninstall --project
  330. ```
  331. </details>
  332. ---
  333. ## Claude Code Integration
  334. <details>
  335. <summary><strong>Setup, commands, and session usage</strong></summary>
  336. DeepRefine works as a Claude Code Agent Skill. The installer writes the
  337. Claude-specific skill file to `.claude/skills/deeprefine/SKILL.md`, along with
  338. independently maintained references under
  339. `.claude/skills/deeprefine/references/` for the refinement workflow, LLM
  340. prompts, and trace/command details.
  341. ### One-time setup
  342. ```bash
  343. cd /path/to/your-kb-project
  344. pip install deeprefine-cli
  345. deeprefine claude install --project
  346. ```
  347. After upgrading the package, run `deeprefine claude install --project` again
  348. to refresh the local skill files. Restart Claude Code, then invoke:
  349. ```text
  350. /deeprefine
  351. ```
  352. ### Claude Code commands
  353. | Command | Description |
  354. |---------|-------------|
  355. | `deeprefine claude install` | Install the Claude Code skill into `.claude/skills/deeprefine/` |
  356. | `deeprefine claude install --user` | Install the Claude Code skill into `~/.claude/skills/deeprefine/` |
  357. | `deeprefine claude uninstall` | Remove the Claude Code skill |
  358. ### Claude Code session
  359. ```text
  360. /deeprefine
  361. ```
  362. Claude Code runs the full refinement loop for pending queries, stops after
  363. `deeprefine review`, and presents the HIGH/MEDIUM/LOW report. Reply with an
  364. explicit apply/approve message only after reviewing the proposed actions.
  365. </details>
  366. ---
  367. ## Terminal CLI (FAISS + API/vLLM)
  368. <details>
  369. <summary><strong>Requirements, environment, workflow, and commands</strong></summary>
  370. Use this section when you want a pure terminal workflow without Cursor `/deeprefine`.
  371. ### Extra requirements
  372. - DeepRefine repository installed in `atlastune`
  373. - Inference backend configured (API or vLLM)
  374. ```bash
  375. conda activate atlastune
  376. cd /path/to/DeepRefine && pip install -e .
  377. pip install deeprefine-cli
  378. # Optional, if DeepRefine repo is elsewhere
  379. export DEEPREFINE_REPO=/path/to/DeepRefine
  380. ```
  381. ### Inference environment (CLI mode)
  382. | Variable | Default |
  383. |----------|---------|
  384. | `DEEPREFINE_LLM_URL` | *(empty; SDK default)* |
  385. | `DEEPREFINE_EMBED_URL` | *(empty; SDK default)* |
  386. | `DEEPREFINE_API_KEY` | fallback to `OPENAI_API_KEY` |
  387. | `DEEPREFINE_LLM_API_KEY` | fallback to `DEEPREFINE_API_KEY` |
  388. | `DEEPREFINE_EMBED_API_KEY` | fallback to `DEEPREFINE_API_KEY` |
  389. | `DEEPREFINE_MODEL` | `gpt-4.1-mini` |
  390. | `DEEPREFINE_EMBED_MODEL` | `text-embedding-3-small` |
  391. ### Terminal workflow
  392. ```bash
  393. cd /path/to/your-kb-project
  394. # Option A: import from graphify memory first (recommended)
  395. deeprefine history sync-memory
  396. deeprefine history list --pending
  397. deeprefine refine # dry-run: proposed actions + review, no graph write
  398. deeprefine refine --apply # optional: write accepted CLI refine changes
  399. # Option B: add one explicit query
  400. deeprefine history add --query "your question"
  401. deeprefine refine # dry-run by default
  402. ```
  403. ### Terminal commands
  404. | Command | Description |
  405. |---------|-------------|
  406. | `deeprefine history add --query "..."` | Append one query to history |
  407. | `deeprefine history list` | List all history rows |
  408. | `deeprefine history sync-memory` | Import graphify memory queries into history |
  409. | `deeprefine history list --pending` | List only unrefined queries |
  410. | `deeprefine refine` | Generate proposed actions for all pending queries; dry-run by default |
  411. | `deeprefine refine --query "..."` | Generate proposed actions for a single query; dry-run by default |
  412. | `deeprefine refine --apply` | Persist accepted CLI refine changes to `graph.json` |
  413. | `deeprefine refine --rebuild-index` | Rebuild FAISS before refine |
  414. | `deeprefine index --rebuild` | Rebuild FAISS cache only |
  415. ## Installation
  416. | Method | Command |
  417. |--------|---------|
  418. | **PyPI** | `pip install deeprefine-cli==0.2.0` |
  419. | **Source** | `pip install -e /path/to/DeepRefine-Skill` |
  420. ```bash
  421. deeprefine --help
  422. # Expect: cursor, copilot, codex, claude, opencode, gemini, history, index, refine, review, apply, loop
  423. ```
  424. </details>
  425. ---
  426. ## License
  427. MIT — see [LICENSE](./LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.