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.
Badge for your README
Markdown
[](/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
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)
- ---
- name: deeprefine
- description: >-
- Agent-native DeepRefine refinement loop — same control flow as DeepRefine.refine(),
- graphify search instead of FAISS, session LLM, dry-run review before approved graph writes.
- disable-model-invocation: false
- ---
- # DeepRefine — Agent refinement loop (strict)
- ## Default safety policy: dry-run only
- A normal `/deeprefine` invocation **MUST NEVER** call `deeprefine apply`.
- The default `/deeprefine` workflow must stop after:
- 1. `deeprefine loop validate`
- 2. `deeprefine review`
- 3. showing the proposed actions and HIGH/MEDIUM/LOW review report to the user
- Then ask the user for explicit approval.
- Only if the user's **next message** explicitly says to approve/apply/write the graph may you run:
- ```bash
- deeprefine apply --refresh-wiki --trace-file ... --refinement-file ...
- deeprefine loop finish --trace-file ... --refinement-file ...
- ```
- 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.
- ---
- You **MUST** implement the **same control flow** as `DeepRefine.refine()` in DeepRefine (`autorefiner/src/deeprefine.py`).
- | Component | Agent mode | CLI `deeprefine refine` |
- |-----------|------------|-------------------------|
- | Retrieval | `graphify query` + k-hop from `graph.json` | FAISS retriever |
- | LLM | **Your session model** | External API / vLLM |
- | Graph writes | Dry-run proposal + `deeprefine review`; `deeprefine apply` only after user approval | Dry-run by default; `--apply` persists |
- ---
- ## FORBIDDEN (hard stop)
- Do **NOT**:
- 1. Run `deeprefine refine` (unless the user explicitly asks for CLI/FAISS mode).
- 2. Call `deeprefine apply` without a valid `loop_trace_<query_id>.json` (CLI will reject).
- 3. Call `deeprefine apply` before running `deeprefine review` and receiving explicit user approval.
- 4. Ignore LOW-confidence review warnings unless the user explicitly requests `--allow-low-confidence`.
- 5. Skip any hop’s `<judge>Yes</judge>` / `<judge>No</judge>` judgement.
- 6. Skip error abduction when `len(interaction_history) > 1`.
- 7. Write `<refinement>` before abduction when refinement is required.
- 8. Hand-edit `graph.json` with Python or ad-hoc JSON patches.
- 9. Ignore pending history and refine only one latest query when unrefined queries already exist.
- 10. Invent a shorter pipeline (“read file → write refinement → apply”).
- If validation fails, **fix the trace and re-run the missing step** — do not bypass with `--skip-trace-check`.
- ---
- ## Constants (match `refine_runner.py` / DeepRefine)
- ```text
- MAX_HOPS = 4
- INCREMENT_HOP = 1
- BASE_TOP_K = 10
- MAX_TRIPLE_NUM_BY_STEP = [5, 10, 15, 20] # cap triples per step
- HISTORY_HORIZON = 4 # abduction uses last N steps
- ```
- ---
- ## Mandatory artifact
- For each query, maintain:
- `graphify-out/.deeprefine/loop_trace_<query_id>.json`
- Create template:
- ```bash
- deeprefine loop init --query "<exact question>"
- ```
- Append each hop to `interaction_history` **before** starting the next hop.
- Run `deeprefine loop validate --trace-file ...` after abduction and before `review` / approved `apply`.
- ---
- ## Query queue selection (default behavior of `/deeprefine`)
- `/deeprefine` must process **all unrefined history queries** first, not just the latest one.
- 1. Sync graphify query memory into DeepRefine history:
- - run: `deeprefine history sync-memory`
- - source dir: `graphify-out/memory/query_*.md`
- - target file: `graphify-out/.deeprefine/history.jsonl`
- 2. Read pending queue from `graphify-out/.deeprefine/history.jsonl`:
- - include rows where `refined != true`
- - dedupe by `id` (first occurrence)
- - preserve file order
- 3. If pending queue is non-empty: set `target_queries = pending_queue`.
- 4. If pending queue is empty: set `target_queries = [current session question]`.
- 5. Run the full refinement loop for **each** query in `target_queries`, one by one.
- 6. For early-exit queries, finish immediately. For refinement-path queries, generate review output and wait for user approval before `apply` + `loop finish`.
- ---
- ## Control flow (must match `DeepRefine.refine()`)
- Pseudocode — follow **exactly**:
- ```text
- target_queries = pending_history_queries() # refined != true, dedupe by id, keep order
- run "deeprefine history sync-memory" before loading pending history
- if target_queries is empty:
- target_queries = [current session question]
- for question in target_queries:
- interaction_history = []
- for step in 1..MAX_HOPS:
- print "[Step: {step}]" # show in chat
- if step == 1:
- # Vector-retrieval equivalent: graphify query on full question
- RUN: graphify query "<question>"
- triples = parse NODE/EDGE → [{subject, relation, object}, ...]
- cap = MAX_TRIPLE_NUM_BY_STEP[0] # 5
- record retrieval.method = "graphify_query"
- else:
- # k-hop expansion from entities in previous hop (NOT a new random search)
- entities = unique subjects/objects from previous triples
- expand 1-hop neighbors from graphify-out/graph.json (or graphify query on entities)
- cap = MAX_TRIPLE_NUM_BY_STEP[step-1]
- record retrieval.method = "k_hop_expansion" or "graphify_query+k_hop_expansion"
- triples = dedupe; len(triples) <= cap
- # Answerable judgement — session LLM, prompts below
- answerable, judgement_raw = LLM_judge(question, triples)
- MUST output ONLY: <judge>Yes</judge> or <judge>No</judge>
- append interaction_history with:
- step, query, num_hops=(step-1)*INCREMENT_HOP, base_top_k=10,
- retrieved_subgraph, answerable, judgement_raw,
- retrieval: {method, evidence: "<command output excerpt>"}
- if answerable:
- BREAK # stop hop loop
- # --- same branch as DeepRefine.refine() line 314+ ---
- if len(interaction_history) <= 1:
- # Early exit: first hop was answerable — NO graph refinement
- set trace.early_exit = true
- deeprefine loop finish --trace-file ... # no --refinement-file
- CONTINUE # move to next pending query
- else:
- # len > 1 → ALWAYS error abduction + actions (even if last hop was Yes)
- error_abduction = LLM_abduction(interaction_history[-HISTORY_HORIZON:])
- MUST output: <abduction>...</abduction>
- actions = LLM_kg_refinement(
- last_hop.retrieved_subgraph,
- error_abduction,
- question,
- source file hints from triples,
- )
- MUST output: <refinement>insert_edge(...)|...</refinement>
- save refinement to graphify-out/.deeprefine/refinement_actions_<id>.txt
- deeprefine loop validate --trace-file ... --refinement-file ...
- deeprefine review --trace-file ... --refinement-file ...
- SHOW review labels: HIGH / MEDIUM / LOW, evidence, warnings, suggested replacements
- HARD STOP: do not modify graph.json in this /deeprefine turn
- Report the proposed actions and HIGH/MEDIUM/LOW review to the user
- Ask for explicit approval; approval must arrive in the user's next message
- # Follow-up turn only, after the user's next message explicitly approves/apply/write:
- if user explicitly approves and no LOW-confidence action remains:
- deeprefine apply --refresh-wiki --trace-file ... --refinement-file ...
- deeprefine loop finish --trace-file ... --refinement-file ...
- if user explicitly accepts LOW-confidence risk in that approval message:
- deeprefine apply --refresh-wiki --allow-low-confidence --trace-file ... --refinement-file ...
- deeprefine loop finish --trace-file ... --refinement-file ...
- ```
- **Critical refinement rule:** refinement runs when `len(interaction_history) > 1`, not only when all judgements are `No`.
- **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`.
- ---
- ## Evidence-aware review rules
- Before any graph write, run:
- ```bash
- deeprefine review --trace-file graphify-out/.deeprefine/loop_trace_<id>.json --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
- ```
- The review must label every action:
- - `HIGH`: direct graph or code evidence exists.
- - `MEDIUM`: k-hop context supports the action, but direct code or exact-edge evidence is missing.
- - `LOW`: endpoint nodes are ambiguous, too broad, cross-community, or cannot be grounded in `graph.json`.
- 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()`.
- `deeprefine apply` refuses LOW-confidence actions by default. Use `--allow-low-confidence` only when the user explicitly approves the risk.
- ---
- ## LLM prompts (verbatim — do not paraphrase)
- ### Judgement (`_answerable_judgement`)
- **System:**
- ```text
- As an advanced judgement assistant, your task is to judge whether the given question is answerable based on the provided KG context.
- Evaluate whether the given question is answerable based on the provided KG context. Output your judgment in the following format:
- <judge>Yes</judge> or <judge>No</judge>
- **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.
- ```
- **User:**
- ```text
- Question: {question}
- Knowledge Graph (KG) context: {triples_string}
- ```
- `{triples_string}` = one triple per line: `subject | relation | object`
- ### Error abduction (`_error_abduction`) — only if `len(interaction_history) > 1`
- **System:**
- ```text
- As an advanced error abduction assistant, your task is to analyze the error reasons based on the given interaction history.
- 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:
- <abduction>...</abduction>
- **Important:** You must think carefully about the interaction history before making your analysis. And output your analysis result directly in the specified format.
- ```
- **User:**
- ```text
- Interaction history: {interaction_history}
- ```
- `{interaction_history}` format (same as DeepRefine):
- ```text
- Step1:
- ['Query': ..., 'Subgraph_hop': ..., 'Subgraph_content': ..., 'Answerable': ...]
- Step2:
- ...
- ```
- ### KG refinement actions (`_kg_refinement_action`) — only if `len(interaction_history) > 1`
- **System:**
- ```text
- 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.
- 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:
- - insert_edge(subject, relation, object): Insert a new edge into the KG to complete the missing information.
- - delete_edge(subject, relation, object): Delete an edge from the KG to remove the redundant information or conflicting information.
- - replace_node(old_entity, new_entity): Replace an entity in the KG to correct the errors or deal with disambiguation.
- Output a series of actions (**within 10 actions**) in the following format:
- <refinement>insert_edge("...", "...", "...")|delete_edge("...", "...", "...")|replace_node("...", "...")|...</refinement>
- **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.
- ```
- **User:**
- ```text
- Original Text: {original_text}
- KG: {triples_string}
- Question: {question}
- Error reasons: {error_reasons}
- ```
- Use **last hop’s** `retrieved_subgraph` as `{triples_string}` (JSON list is OK in trace; string form for the prompt).
- ---
- ## Per-query checklist (report in chat)
- Copy and tick each item in your final message:
- ```text
- [ ] Backup: graphify-out/.deeprefine/graph.json.bak
- [ ] loop_trace_<id>.json created
- [ ] Step 1: graphify query executed (evidence in trace)
- [ ] Each step: <judge>Yes|No</judge> shown in chat
- [ ] Hops stopped on Yes OR reached MAX_HOPS
- [ ] early_exit OR (abduction + refinement) per DeepRefine branch
- [ ] deeprefine loop validate passed
- [ ] deeprefine review generated with HIGH/MEDIUM/LOW labels
- [ ] graph.json intentionally left unchanged pending next-message approval OR user approved in a follow-up message
- [ ] deeprefine apply skipped in normal /deeprefine turn; only run after next-message approval
- [ ] deeprefine loop finish
- ```
- ---
- ## Commands (in order)
- ```bash
- # 0. KB project root; graphify-out/graph.json exists
- mkdir -p graphify-out/.deeprefine
- cp graphify-out/graph.json graphify-out/.deeprefine/graph.json.bak
- # 1. Sync graphify query memory to deeprefine history first.
- deeprefine history sync-memory
- # 2. Build target query list:
- # - preferred: all pending from history.jsonl (refined != true)
- # - fallback: current session question (single query)
- deeprefine history list --pending
- # 3. For EACH query in target list:
- deeprefine loop init --query "<question>"
- # 4–7. For each hop: graphify/graph read → judge → append to loop_trace_*.json
- # 8a. Early exit (len(history)==1 and answerable)
- deeprefine loop validate --trace-file graphify-out/.deeprefine/loop_trace_<id>.json
- deeprefine loop finish --trace-file graphify-out/.deeprefine/loop_trace_<id>.json
- # 8b. Refinement path (len(history)>1): dry-run review first
- deeprefine loop validate --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
- deeprefine review --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
- # HARD STOP.
- # A normal /deeprefine run must end here.
- # Report the review to the user and ask for explicit approval.
- # Do NOT run deeprefine apply in the same /deeprefine turn.
- # Approval-only follow-up commands, only after the user explicitly says approve/apply:
- deeprefine apply --refresh-wiki --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
- # Optional explicit risk override:
- # deeprefine apply --refresh-wiki --allow-low-confidence --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
- deeprefine loop finish --trace-file ... --refinement-file graphify-out/.deeprefine/refinement_actions_<id>.txt
- # 9. Repeat step 3..8 until all pending queries are reviewed/finished.
- ```
- ---
- ## `loop_trace_*.json` schema
- ```json
- {
- "schema_version": 1,
- "mode": "agent-loop",
- "query": "what is dulce?",
- "query_id": "5cdc0798eb59b486",
- "constants": { "max_hops": 4, "increment_hop": 1, "base_top_k": 10,
- "max_triple_num_by_step": [5, 10, 15, 20], "history_horizon_size": 4 },
- "interaction_history": [
- {
- "step": 1,
- "num_hops": 0,
- "base_top_k": 10,
- "query": "what is dulce?",
- "retrieval": {
- "method": "graphify_query",
- "evidence": "graphify query \"what is dulce?\" → …"
- },
- "retrieved_subgraph": [
- {"subject": "A", "relation": "r", "object": "B"}
- ],
- "answerable": false,
- "judgement_raw": "<judge>No</judge>"
- }
- ],
- "error_abduction_reason": "…",
- "error_abduction_raw": "<abduction>…</abduction>",
- "refinement_action_file": "graphify-out/.deeprefine/refinement_actions_<id>.txt",
- "early_exit": false
- }
- ```
- ---
- ## Optional: CLI mode (FAISS + API)
- Only when the user **explicitly** requests `deeprefine refine` / full runtime:
- ```bash
- conda activate atlastune
- export DEEPREFINE_EMBED_URL=... DEEPREFINE_LLM_URL=...
- deeprefine refine --query "..." # dry-run proposal only
- # deeprefine refine --query "..." --apply # only when the user explicitly wants CLI mode to write graph.json
- ```
- ---
- ## Paths
- - `graphify-out/graph.json`
- - `graphify-out/.deeprefine/loop_trace_*.json` (**required**)
- - `graphify-out/.deeprefine/refinement_actions_*.txt`
- - `graphify-out/.deeprefine/refinement_results_*.jsonl`
- - `graphify-out/.deeprefine/proposed_refinement_review_*.md`
- - `graphify-out/.deeprefine/proposed_refinement_review_*.json`
- - `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)
- <div align="center">
- # DeepRefine-Skill
- <table style="border: none; margin: 0 auto; padding: 0; border-collapse: collapse;">
- <tr>
- <td align="center" style="vertical-align: middle; padding: 10px; border: none; width: 250px;">
- <img src="./assets/icons3.png" alt="DeepRefine Logo" width="200" style="margin: 0; padding: 0; display: block;"/>
- </td>
- <td align="left" style="vertical-align: middle; padding: 10px 0 10px 30px; border: none;">
- <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;">██████╗ ███████╗███████╗██████╗ ██████╗ ███████╗███████╗██╗███╗ ██╗███████╗
- ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔══██╗██╔════╝██╔════╝██║████╗ ██║██╔════╝
- ██║ ██║█████╗ █████╗ ██████╔╝██████╔╝█████╗ █████╗ ██║██╔██╗ ██║█████╗
- ██║ ██║██╔══╝ ██╔══╝ ██╔═══╝ ██╔══██╗██╔══╝ ██╔══╝ ██║██║╚██╗██║██╔══╝
- ██████╔╝███████╗███████╗██║ ██║ ██║███████╗██║ ██║██║ ╚████║███████╗
- ╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝</pre>
- </td>
- </tr>
- </table>
- [](https://pypi.org/project/deeprefine-cli/0.2.0/)
- [](https://pypi.org/project/deeprefine-cli/0.2.0/)
- [](https://arxiv.org/pdf/2605.10488)
- [](https://github.com/HKUST-KnowComp/DeepRefine)
- </div>
- 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.
- <p align="center">
- <img src="assets/demo-typing-deeprefine.svg" alt="Demo: /deeprefine" />
- </p>
- It refines your graphify knowledge graph for better future retrieval and Q&A quality.
- Supported agent frameworks:
- <p>
- <a href="https://cursor.com" title="Cursor"><img src="./assets/cursor_CUBE_25D.png" alt="Cursor" height="40"/></a>
- <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>
- <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>
- <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>
- <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>
- <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>
- </p>
- ---
- ## News
- - **[2026/7/10] v0.2.0** - Claude Code and OpenCode adapters: `deeprefine claude install` / `deeprefine opencode install`, bundled skill + command templates.
- - **[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.
- - **[2026/6/24] v0.1.9** - Codex skill supported.
- - **[2026/6/18] v0.1.9** - Gemini CLI and Copilot CLI supported.
- - **[2026/6/17] v0.1.9** - Added dry-run-first refinement, evidence-aware action review, ambiguous-node warnings, and LOW-confidence apply guard.
- - **[2026/6/15] v0.1.8** - Aligned interaction memory with LLM-Wiki (graphify) and fixed the single query refinement issue.
- - **[2026/6/2] v0.1.7** — Cursor skill + `deeprefine refine` with configurable API. And strict DeepRefine agent loop.
- ## Agent CLI (Recommended)
- This is the default mode and the main workflow for this project.
- ### One-time setup
- ```bash
- 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.
- ### Typical session (Agent CLI)
- ```bash
- /graphify .
- /graphify ./ --wiki
- /graphify query "your question 1"
- /graphify query "your question 2"
- # ..
- /deeprefine
- ```
- ### What `/deeprefine` does now (default queue behavior)
- <details>
- <summary><strong>Procedures:</strong></summary>
- When you run `/deeprefine`, it should follow this order:
- 1. `deeprefine history sync-memory`
- - import queries from `graphify-out/memory/query_*.md`
- - write to `graphify-out/.deeprefine/history.jsonl`
- 2. load pending queries from `history.jsonl` (`refined != true`)
- 3. refine pending queries sequentially
- 4. for refinement-path queries, generate `<refinement>` actions and run `deeprefine review`
- 5. stop in dry-run mode and show the review report; do **not** modify `graph.json` yet
- 6. only after user approval, run `deeprefine apply --refresh-wiki` and then `deeprefine loop finish`
- </details>
- ### Agent artifacts
- ```text
- graphify-out/
- ├── graph.json # graphify main graph; unchanged until apply approval
- ├── memory/
- │ └── query_*.md # graphify query logs (sync source)
- └── .deeprefine/
- ├── history.jsonl # DeepRefine-maintained history queue
- ├── graph.json.bak # backup before first apply in this run
- ├── checkpoints/graph.checkpoint.<seq>.json # post-state graph after each apply
- ├── checkpoints.json # checkpoint timeline registry
- ├── loop_trace_<query_id>.json # per-query loop audit trace
- ├── refinement_results_<YYYYMMDD>.jsonl # per-day run log
- ├── refinement_actions_*.txt # optional; only when refinement path is taken
- ├── proposed_refinement_actions_*.txt # CLI dry-run proposed actions
- ├── proposed_refinement_review_*.md # evidence-aware review report
- └── proposed_refinement_review_*.json # optional structured review report
- ```
- ### Agent-related commands
- Run from your KB project root.
- | Command | Description |
- |---------|-------------|
- | `deeprefine cursor install` | Install `/deeprefine` skill for Cursor (`.cursor/skills/deeprefine/`) |
- | `deeprefine cursor install --user` | Install Cursor skill for all projects (`~/.cursor/skills/`) |
- | `deeprefine copilot install` | Install `/deeprefine` skill for Copilot CLI (`.github/skills/deeprefine/`) |
- | `deeprefine copilot install --user` | Install Copilot CLI skill for all projects (`~/.copilot/skills/`) |
- | `deeprefine copilot uninstall` | Remove Copilot CLI skill |
- | `deeprefine codex install` | Install `$deeprefine` skill for Codex (`.agents/skills/deeprefine/`) |
- | `deeprefine codex install --user` | Install Codex skill for all projects (`~/.codex/skills/deeprefine/`) |
- | `deeprefine codex uninstall` | Remove Codex skill |
- | `deeprefine claude install` | Install `/deeprefine` skill for Claude Code (`.claude/skills/deeprefine/`) |
- | `deeprefine claude install --user` | Install Claude Code skill for all projects (`~/.claude/skills/deeprefine/`) |
- | `deeprefine claude uninstall` | Remove the Claude Code skill |
- | `deeprefine opencode install` | Install `/deeprefine` skill + commands for OpenCode (`.opencode/`) |
- | `deeprefine opencode install --user` | Install OpenCode skill for all projects (`~/.opencode/`) |
- | `deeprefine opencode uninstall` | Remove the OpenCode skill and commands |
- | `deeprefine gemini path` | Print the extension root used for Gemini CLI |
- | `deeprefine gemini link` | Link the current source checkout with `gemini extensions link` |
- | `deeprefine gemini install` | Install the bundled extension with `gemini extensions install` |
- | `deeprefine gemini install --copy-only` | Manual fallback copy to `~/.gemini/extensions/deeprefine-skill` |
- | `deeprefine gemini uninstall` | Remove the extension with Gemini CLI's manager |
- | `deeprefine history sync-memory` | Import `graphify-out/memory/query_*.md` into DeepRefine history |
- | `deeprefine history list --pending` | Show unrefined queue |
- | `deeprefine loop init --query "..."` | Create `loop_trace_<id>.json` template |
- | `deeprefine loop validate --trace-file T` | Validate trace against DeepRefine control flow |
- | `deeprefine review --trace-file T --refinement-file F` | Review proposed actions with HIGH/MEDIUM/LOW evidence labels; no graph write |
- | `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 |
- | `deeprefine apply --refresh-wiki --allow-low-confidence --trace-file T --refinement-file F` | Refresh the Wiki while explicitly overriding the LOW-confidence guard |
- | `deeprefine loop finish --trace-file T [--refinement-file F]` | Persist results and mark history refined |
- ### Evidence-aware review and safe apply
- `/deeprefine` should default to dry-run-first behavior. Proposed actions are reviewed before they can modify `graphify-out/graph.json`. Each action is labeled:
- | Label | Meaning |
- |-------|---------|
- | `HIGH` | Direct graph or code evidence exists. |
- | `MEDIUM` | k-hop context supports the action, but direct code or exact-edge evidence is missing. |
- | `LOW` | Node names are ambiguous, too broad, cross-community, or cannot be grounded in `graph.json`. |
- Bare function names such as `main()`, `run()`, `train()`, `test()`, and `setup()` are treated as ambiguous. Prefer file-qualified names:
- ```text
- BAD: insert_edge("main()", "calls", "Trainer")
- GOOD: insert_edge("pretraining/pretraining_CLIP_fine-grained.py::main()", "calls", "Trainer")
- ```
- `deeprefine apply` refuses LOW-confidence actions by default. Use `--allow-low-confidence` only when the user explicitly accepts the risk.
- 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.
- ---
- ## Codex Integration
- <details>
- <summary><strong>Setup, commands, and session usage</strong></summary>
- DeepRefine works as a Codex skill. The installer writes the Codex-specific
- skill file to `.agents/skills/deeprefine/SKILL.md` and UI metadata to
- `.agents/skills/deeprefine/agents/openai.yaml`. It also installs focused
- references under `.agents/skills/deeprefine/references/` for the refinement
- workflow, LLM prompts, and trace/command details.
- ### One-time setup
- ```bash
- cd /path/to/your-kb-project
- pip install deeprefine-cli
- deeprefine codex install --project
- ```
- After upgrading the package, run `deeprefine codex install --project` again to
- refresh the local skill files. Restart or reload Codex, then invoke:
- ```text
- $deeprefine
- /deeprefine
- ```
- ### Codex commands
- | Command | Description |
- |---------|-------------|
- | `deeprefine codex install` | Install the Codex skill into `.agents/skills/deeprefine/` |
- | `deeprefine codex install --user` | Install the Codex skill into `~/.codex/skills/deeprefine/` |
- | `deeprefine codex uninstall` | Remove the Codex skill |
- ### Codex session
- ```text
- $deeprefine
- ```
- Codex runs the full agent-native refinement loop for pending queries, stops after
- `deeprefine review`, and presents the HIGH/MEDIUM/LOW report. Reply with an
- explicit apply/approve message only after reviewing the proposed actions.
- See [`docs/codex.md`](docs/codex.md) for details.
- </details>
- ---
- ## Copilot CLI Integration
- <details>
- <summary><strong>Setup, commands, and session usage</strong></summary>
- DeepRefine works as a GitHub Copilot CLI agent skill. The skill file is
- installed into `.github/skills/deeprefine/SKILL.md` and auto-discovered by
- Copilot. Shell commands are pre-approved via `allowed-tools: shell`.
- ### One-time setup
- ```bash
- cd /path/to/your-kb-project
- pip install deeprefine-cli
- deeprefine copilot install --project
- ```
- After upgrading the package, run `deeprefine copilot install --project` again
- to refresh the local skill file. Start a Copilot CLI session and reload:
- ```text
- /skills reload
- /skills info deeprefine
- ```
- ### Mode detection
- Copilot CLI does not natively support sub-commands, so the skill uses
- keyword-based mode detection in the SKILL.md preamble:
- | Mode | Trigger keywords | Behavior |
- |------|-----------------|----------|
- | **Full workflow** | `/deeprefine`, "refine", "improve", "fix" | Full refinement loop; stops after dry-run review; asks for approval |
- | **Review only** | "review", "check", "audit", "inspect", "dry-run" | Reads trace + refinement file; shows HIGH/MEDIUM/LOW report; no graph writes |
- | **Apply only** | "approve", "apply", "write", "go ahead" | Runs `deeprefine apply` only after a prior review; requires explicit user approval in the current message |
- ### Copilot CLI session
- ```text
- /deeprefine
- ```
- The agent runs the full refinement loop for all pending queries. For
- refinement-path queries, it stops after the dry-run review and asks:
- ```text
- [HIGH] insert_edge("trainer.py::train_epoch()", "calls", "validate()")
- Evidence: Direct code evidence in trainer.py.
- [MEDIUM] insert_edge("data.py::load()", "imports", "torch")
- Warning: No direct code evidence found.
- Apply only after review. Approve?
- ```
- Reply "apply" or "go ahead" to proceed; the agent will run
- `deeprefine apply` in the follow-up turn.
- </details>
- ---
- ## Gemini CLI Integration
- <details>
- <summary><strong>Setup, commands, and session usage</strong></summary>
- DeepRefine can also be used as a Gemini CLI extension. This keeps the same safe,
- dry-run-first DeepRefine workflow while making `/deeprefine` available inside
- Gemini CLI.
- ### One-time setup for local development
- ```bash
- cd /path/to/DeepRefine-Skill
- pip install -e .
- deeprefine gemini link
- ```
- `deeprefine gemini link` calls Gemini CLI's official extension manager:
- ```bash
- gemini extensions link /path/to/DeepRefine-Skill
- ```
- Restart Gemini CLI after linking. Then check:
- ```text
- /extensions list
- /commands list
- ```
- Expected commands:
- ```text
- /deeprefine
- /deeprefine:review
- /deeprefine:apply
- ```
- ### Gemini CLI commands
- | Command | Description |
- |---------|-------------|
- | `deeprefine gemini path` | Print the extension root used for Gemini CLI |
- | `deeprefine gemini link` | Link the current source checkout with `gemini extensions link` |
- | `deeprefine gemini install` | Install the bundled extension with `gemini extensions install` |
- | `deeprefine gemini install --copy-only` | Manual fallback copy to `~/.gemini/extensions/deeprefine-skill` |
- | `deeprefine gemini uninstall` | Remove the extension with Gemini CLI's manager |
- For normal source development, prefer `deeprefine gemini link`. It makes the
- extension visible to `/extensions list`, whereas copying files alone may not
- register the extension in newer Gemini CLI versions.
- ### Gemini CLI session
- ```bash
- gemini
- ```
- Then run:
- ```text
- /deeprefine
- /deeprefine:review "Why is the graph missing the data loading path?"
- /deeprefine:apply "Apply the approved refinement actions from the valid trace."
- ```
- The extension files are located at the repository root and are also bundled under
- `deeprefine_skill/gemini_extension/` for wheel installs. See
- [`docs/gemini-cli.md`](docs/gemini-cli.md) for details.
- </details>
- ## OpenCode Integration
- <details>
- <summary><strong>Setup, commands, and session usage</strong></summary>
- ### Prerequisites
- - **OpenCode CLI** installed and configured
- - **graphify** CLI available on your PATH
- - **Python 3.10+** with `deeprefine-cli` installed
- - A `graphify-out/graph.json` knowledge graph in your project
- ### Setup
- ```bash
- # Install into the current project
- deeprefine opencode install --project
- # Install globally (all projects)
- deeprefine opencode install --user
- ```
- This installs **4 files**:
- | Destination | Source | Purpose |
- |------------|--------|---------|
- | `.opencode/skills/deeprefine/SKILL.md` | `SKILL_OPENCODE.md` | Agent harness with 6 OpenCode-native optimizations |
- | `.opencode/commands/deeprefine.md` | `commands/opencode/deeprefine.md` | Full workflow entrypoint (`/deeprefine`) |
- | `.opencode/commands/deeprefine-review.md` | `commands/opencode/deeprefine-review.md` | Review-only entrypoint (`/deeprefine-review`) |
- | `.opencode/commands/deeprefine-apply.md` | `commands/opencode/deeprefine-apply.md` | Apply-only entrypoint (`/deeprefine-apply`) |
- ### Commands
- | Command | Description |
- |---------|-------------|
- | `/deeprefine` | Full pipeline: sync → judge → abduction → refinement → 5-Oracle review → (await approval) → apply → post-apply verify |
- | `/deeprefine-review` | Review only: read existing actions → 5-Oracle audit → evidence review → present results |
- | `/deeprefine-apply` | Apply only: read reviewed actions → confirm → apply → post-apply verify → finish |
- ### Model Configuration
- OpenCode supports per-phase model routing via environment variables:
- | Variable | Phase | Purpose |
- |----------|-------|---------|
- | `DEEPREFINE_JUDGE_MODEL` | Judgement (`<judge>Yes/No</judge>`) | Fast, cheap model for binary classification (e.g., `gpt-4o-mini`) |
- | `DEEPREFINE_REFINE_MODEL` | Abduction + Refinement | Strong reasoning model for complex causal analysis (e.g., `claude-sonnet-4-20250514`) |
- If either variable is unset, the session default model is used.
- ### OpenCode-Native Optimizations
- DeepRefine on OpenCode includes 6 platform-native optimizations not available in Cursor or Cline:
- 1. **Parallel query processing** — Multiple pending queries are dispatched to parallel subagents via `task()`, reducing wall-clock time to ~1 query's duration
- 2. **Phase-specific model routing** — Binary judgement uses a cheap model; complex abduction/refinement uses a strong model
- 3. **Structured progress tracking** — `todowrite()` replaces text checklists, enabling real-time progress visibility and cross-session resumption
- 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
- 5. **Post-apply auto-verification** — After applying refinement actions, the original query is re-run to confirm the graph fix actually resolved the issue
- 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
- ### Uninstall
- ```bash
- deeprefine opencode uninstall --project
- ```
- </details>
- ---
- ## Claude Code Integration
- <details>
- <summary><strong>Setup, commands, and session usage</strong></summary>
- DeepRefine works as a Claude Code Agent Skill. The installer writes the
- Claude-specific skill file to `.claude/skills/deeprefine/SKILL.md`, along with
- independently maintained references under
- `.claude/skills/deeprefine/references/` for the refinement workflow, LLM
- prompts, and trace/command details.
- ### One-time setup
- ```bash
- cd /path/to/your-kb-project
- pip install deeprefine-cli
- deeprefine claude install --project
- ```
- After upgrading the package, run `deeprefine claude install --project` again
- to refresh the local skill files. Restart Claude Code, then invoke:
- ```text
- /deeprefine
- ```
- ### Claude Code commands
- | Command | Description |
- |---------|-------------|
- | `deeprefine claude install` | Install the Claude Code skill into `.claude/skills/deeprefine/` |
- | `deeprefine claude install --user` | Install the Claude Code skill into `~/.claude/skills/deeprefine/` |
- | `deeprefine claude uninstall` | Remove the Claude Code skill |
- ### Claude Code session
- ```text
- /deeprefine
- ```
- Claude Code runs the full refinement loop for pending queries, stops after
- `deeprefine review`, and presents the HIGH/MEDIUM/LOW report. Reply with an
- explicit apply/approve message only after reviewing the proposed actions.
- </details>
- ---
- ## Terminal CLI (FAISS + API/vLLM)
- <details>
- <summary><strong>Requirements, environment, workflow, and commands</strong></summary>
- Use this section when you want a pure terminal workflow without Cursor `/deeprefine`.
- ### Extra requirements
- - DeepRefine repository installed in `atlastune`
- - Inference backend configured (API or vLLM)
- ```bash
- conda activate atlastune
- cd /path/to/DeepRefine && pip install -e .
- pip install deeprefine-cli
- # Optional, if DeepRefine repo is elsewhere
- export DEEPREFINE_REPO=/path/to/DeepRefine
- ```
- ### Inference environment (CLI mode)
- | Variable | Default |
- |----------|---------|
- | `DEEPREFINE_LLM_URL` | *(empty; SDK default)* |
- | `DEEPREFINE_EMBED_URL` | *(empty; SDK default)* |
- | `DEEPREFINE_API_KEY` | fallback to `OPENAI_API_KEY` |
- | `DEEPREFINE_LLM_API_KEY` | fallback to `DEEPREFINE_API_KEY` |
- | `DEEPREFINE_EMBED_API_KEY` | fallback to `DEEPREFINE_API_KEY` |
- | `DEEPREFINE_MODEL` | `gpt-4.1-mini` |
- | `DEEPREFINE_EMBED_MODEL` | `text-embedding-3-small` |
- ### Terminal workflow
- ```bash
- cd /path/to/your-kb-project
- # Option A: import from graphify memory first (recommended)
- deeprefine history sync-memory
- deeprefine history list --pending
- deeprefine refine # dry-run: proposed actions + review, no graph write
- deeprefine refine --apply # optional: write accepted CLI refine changes
- # Option B: add one explicit query
- deeprefine history add --query "your question"
- deeprefine refine # dry-run by default
- ```
- ### Terminal commands
- | Command | Description |
- |---------|-------------|
- | `deeprefine history add --query "..."` | Append one query to history |
- | `deeprefine history list` | List all history rows |
- | `deeprefine history sync-memory` | Import graphify memory queries into history |
- | `deeprefine history list --pending` | List only unrefined queries |
- | `deeprefine refine` | Generate proposed actions for all pending queries; dry-run by default |
- | `deeprefine refine --query "..."` | Generate proposed actions for a single query; dry-run by default |
- | `deeprefine refine --apply` | Persist accepted CLI refine changes to `graph.json` |
- | `deeprefine refine --rebuild-index` | Rebuild FAISS before refine |
- | `deeprefine index --rebuild` | Rebuild FAISS cache only |
- ## Installation
- | Method | Command |
- |--------|---------|
- | **PyPI** | `pip install deeprefine-cli==0.2.0` |
- | **Source** | `pip install -e /path/to/DeepRefine-Skill` |
- ```bash
- deeprefine --help
- # Expect: cursor, copilot, codex, claude, opencode, gemini, history, index, refine, review, apply, loop
- ```
- </details>
- ---
- ## License
- MIT — see [LICENSE](./LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.