# Project Query

> Use when answering, discussing, locating, or synthesizing project questions from a project-local `.llm-wiki`, including cross-project refs, related requirements, bugs, source proxies, working-context pages, design docs, artifacts, dashboard state, and development notes without starting implementation.

- Skill: `huajiexiewenfeng/project-query` (Agent Skill)
- Install (CLI): `npx skillmds@latest add huajiexiewenfeng/project-query`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huajiexiewenfeng/project-query/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: huajiexiewenfeng (https://skillmd.com/u/huajiexiewenfeng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/huajiexiewenfeng/project-query

---


# Project Query

## Purpose

Answer and discuss project questions from a project-local `.llm-wiki` and its linked source materials.

This skill is the Project Develop Copilot equivalent of an Obsidian LLM Wiki query flow. It helps the user quickly find relevant requirements, development docs, bug notes, artifacts, dashboard state, and source proxies, then assemble a small discussion context for follow-up thinking.

It is read-only by default. It does not create Change Briefs, Bug Briefs, working-context pages, dashboard updates, or code changes unless the user explicitly asks to save or act on the discussion. When the user explicitly asks to update or refresh the dashboard, this skill may run `dashboard-refresh` mode and update only dashboard-related files.

## When to Use

Use when the user asks to:

- answer a project question from `.llm-wiki`
- find the requirement, bug, design doc, source proxy, or artifact related to a topic
- discuss project architecture, decisions, progress, or tradeoffs using existing project context
- summarize what the project wiki says about a feature, module, bug, or decision
- answer "what exists in this project / how is it called / how was it designed" questions about a module, integration, API, or feature; start from `.llm-wiki` context first, then verify key facts against source code when needed
- answer cross-service ownership and contract questions such as which remote project owns an interface, Feign client, MQTT topic, HTTP API, RPC endpoint, shared DB, or shared config
- assemble context for later development without starting development yet
- compare related requirements, bugs, source materials, or working-context pages
- locate evidence before deciding whether to create a requirement, fix a bug, or review a change
- update, refresh, or sync the static project dashboard/progress page from existing `.llm-wiki` evidence

Example triggers:

- "基于这个项目的 llm wiki 回答"
- "从项目 wiki 里找一下这个需求"
- "这个功能之前有什么开发文档"
- "帮我找到相关 requirement / bug / working-context"
- "先把上下文找出来，我们讨论一下"
- "what does the project wiki say about this module"
- "find related project docs before we decide what to do"
- "这个项目里面，大疆 API 适配，直播相关的内容有哪些？如何通过 API 调用"
- "更新项目看板"
- "刷新 dashboard"
- "同步项目状态页"
- "update progress dashboard"

## When Not to Use

- Do not use for implementation after the user clearly asks to develop; route to `project-develop`.
- Do not use for bug diagnosis/fix after the user clearly asks to fix; route to `project-fix`.
- Do not use for adding new source material; route to `project-ingest`.
- Do not use for finish sync; route to `project-finish`.
- Do not use for commit/PR review; route to `project-review`.
- Do not save synthesis back to `.llm-wiki` unless the user explicitly asks to save it.
- Do not use dashboard refresh to imply finish, done, verified, or review-passed status; route to `project-finish` or `project-review` for those claims.

## Owned Gates

- Lightweight Boundary
- Context Recovery Gate
- Finish Sync Gate in explicit `dashboard-refresh` mode

## Initialization Gate

Run after resolving the project root and before a wiki query, cross-project lookup, or dashboard refresh.

- `wiki_required: true`
- `on_missing_wiki: route project-init`
- `direct_invocation_missing_wiki: dispatch-project-init`
- When directly invoked and no parent router is active, treat the bootstrap handoff as an internal routing message, not a terminal user-facing response.
- Unless an explicit no-write constraint or root-confidence check requires confirmation, continue through `project-init` in the same turn, consume its return handoff, and resume only at a supported next gate.
- `pending_primary_stage: project-query`
- Preserve the requested evidence question or dashboard action as `pending_intent`.
- `source-only_without_wiki: lightweight-answer`
- `explicit_no_write_missing_wiki: confirm-before-init`
- If `<project_root>/.llm-wiki/` is absent, stop and return a Context Handoff to `project-init` with `bootstrap_mode: automatic-minimal`. Do not present source fallback as a successful wiki query or dashboard refresh.
- Default query read-only behavior does not forbid automatic minimal bootstrap. If the user explicitly says no writes or forbids file changes, do not let `project-init` write until the user confirms initialization.
- If the user explicitly wants only a small source-based answer with no lifecycle state, return to the router as `lightweight-answer` instead of continuing in `project-query`.

On the missing-wiki branch, emit this minimal handoff:

```text
bootstrap_handoff:
  project_root: <resolved project root>
  pending_intent: <preserved evidence question or dashboard request>
  pending_primary_stage: project-query
  requested_stage_or_bridge: project-init
  bootstrap_mode: automatic-minimal
  current_gate: Initialization Gate
```

## Required First Check

1. Resolve project root.
2. Run the Initialization Gate before resolving child references or wiki targets.
3. Resolve optional shared references from `../references/` or local `references/`. If `lifecycle-router.md`, `flow-record.md`, or `progress-dashboard.md` is missing, continue in degraded mode using the minimum rules in this skill; report the missing deep references and keep answers read-only unless the user explicitly asks to write dashboard state.
4. Confirm `.llm-wiki/` exists. The directory itself proves that the project has a local LLM Wiki; `.llm-wiki/index.md` is an optional navigation page, not the existence sentinel.
5. Decide whether this is read-only project query or full lifecycle work.
6. Identify likely query targets: requirements, bugs, sources, working-context, modules, artifacts, dashboard, session-digests, log.
7. If the user asks only to refresh dashboard/progress state, enter `dashboard-refresh` mode.
8. If the user asks to act beyond dashboard refresh, route to the appropriate lifecycle stage after answering or ask one minimal clarification.

## Core Process

Read as needed:

- `../references/north-star.md`
- `../references/lifecycle-router.md`
- `../references/lifecycle-gates.md`
- `../references/project-graph.md`
- `../references/cross-project-refs.md`
- `../references/base-graph.md`
- `../references/progress-dashboard.md`
- `../references/flow-record.md`
- `.llm-wiki/README.md`
- `.llm-wiki/index.md` when present
- `.llm-wiki/modules/index.md`
- `.llm-wiki/ingest/index.md`
- `.llm-wiki/artifacts/index.md`
- `.llm-wiki/cross-refs/index.md`
- `.llm-wiki/project-graph/edges.md`
- `.llm-wiki/project-graph/candidates.md`
- `.llm-wiki/cross-refs/registry.local.json`
- `.llm-wiki/registry.local.json`
- `.llm-wiki/log.md`
- `.llm-wiki/session-digests/`
- relevant `.llm-wiki/requirements/*.md`
- relevant `.llm-wiki/bugs/*.md`
- relevant `.llm-wiki/sources/*.md`
- relevant `.llm-wiki/working-context/*.md`

Reference availability policy:

- Shared references are deep references, not startup requirements.
- Do not stop solely because `../references/` is missing.
- In degraded mode, query can still read `.llm-wiki` indexes and return evidence/inference separation.
- Dashboard refresh in degraded mode must not claim done/verified/progress status unless existing Flow Record evidence is clear.

Workflow:

1. Resolve project root and `.llm-wiki` root.
2. Build the wiki entrypoint map from the available targets under `.llm-wiki/`. Prefer `.llm-wiki/README.md` and `.llm-wiki/index.md` when present, but do not declare the wiki absent just because either file is missing.
3. Search lightweight indexes and directory entrypoints before deep-reading pages.
4. Read the smallest relevant set of wiki pages.
5. For cross-service questions, use Project Graph lookup before inferring remote ownership or contracts:
   - Read `.llm-wiki/cross-refs/index.md` as the pin layer.
   - If a pin matches, follow `edge_id` into `.llm-wiki/project-graph/edges.md`; never treat pin fields as contract facts.
   - If no pin matches, search `.llm-wiki/project-graph/edges.md`.
   - If no edge matches, search `.llm-wiki/project-graph/candidates.md` and label the result `candidate only`.
   - If remote evidence is needed, resolve the remote project through registry order from `cross-project-refs.md`: current project preferred registry, legacy current-project registry, Base Graph registry when Base is discoverable, then legacy global fallback as read-only compatibility.
   - If no registry mapping exists, ask for the local path. With Base, write Base Graph `.llm-wiki/registry.local.json` after confirmation; without Base, write only current project `.llm-wiki/registry.local.json`. Ensure `.gitignore` contains the three local-only ignore lines when writing current-project registry.
   - Before reading remote wiki or source, output a cross-project boundary check with `scope: read-only`.
   - Use `verification_required: wiki-only-allowed` for ownership or clue-finding answers; state when source verification was not performed.
   - Do not write Change Brief, Bug Brief, Flow Record, dashboard, edges, candidates, pins, Base tracked files, or remote project files during ordinary query.
   - If the user wants to register a missing relation after query, hand off to `project-maintain graph-register` after confirmation.
   - For large cross-service context, discover Base Graph through `LLM_WIKI_BASE_GRAPH_PATH` or `~/.llm-wiki/base-graph.local.json`; if found, read Base `base-graph/overview.md` and `base-graph/project-catalog.md` as read-only discussion context. If Base is not found, continue with current-project graph and state the downgrade.
6. Fall back to original source files only when wiki summaries are insufficient or stale.
7. Separate sourced wiki facts from inference.
8. Return a concise answer and a Project Context Pack.
9. In `dashboard-refresh` mode, update only `.llm-wiki/dashboard/progress.html`, dashboard artifact metadata, and a short `.llm-wiki/log.md` entry when needed. Build flow board cards from Flow Records in Change Briefs, Bug Briefs, and working-context pages using `progress-dashboard.md` projection rules.
   - Treat Flow Record as the lifecycle status authority.
   - Treat artifact registry as the artifact/path/discoverability authority.
   - Treat dashboard as a projection only.
   - Do not edit Change Briefs, Bug Briefs, working-context Flow Records, or verification status during dashboard-only refresh.
   - If a dashboard card disagrees with Flow Record evidence, downgrade/remove the card or report drift; do not rewrite Flow Record to match the card.
10. Before reporting a dashboard refresh complete, run the Progress Dashboard consistency checks: every distinct `flow_id` and `parent_flow_id`/child Flow Record discovered from `.llm-wiki` must have visible board cards for each eligible Flow Record row, matching `dashboardData.flowRecords` entries, and correct lane counts. Fix drift before returning.
11. Offer upgrade routes only when useful: develop, fix, ingest, finish, review, evaluator, or Dolores.

## Anti-Corruption Read Discipline

Before using `.llm-wiki` content as project fact, downgrade any item with these signals to clue-only status:

- `freshness-expired`
- `stale-source-anchor`
- `coarse-stale-source-anchor`
- `missing-verified-commit`
- `unreachable-verified-commit`
- `unverifiable-anchor`
- `source_refs[*].dirty_at_capture`
- `source_refs[*].needs_commit_resolution`

Clue-only content may guide where to look next, but it must not be presented as current fact. Prefer current source code, tests, configuration, runtime evidence, and source-verified Project Graph edges. If wiki content conflicts with current source evidence, state that source wins and that the wiki item needs re-verification.

## Mode / Entry Selection

| Mode | Use when |
|---|---|
| `quick-lookup` | user asks where a requirement/doc/page/artifact is |
| `wiki-answer` | user asks a question answerable from project wiki pages |
| `discussion-context` | user wants context assembled before discussion |
| `evidence-map` | user asks which docs, requirements, bugs, or artifacts relate to a topic |
| `cross-project-lookup` | user asks which remote project owns an interface/topic/client/config/callback or asks for a cross-service contract clue |
| `base-overview-query` | user asks for large cross-service context and Base Graph is discoverable |
| `dashboard-refresh` | user explicitly asks to refresh or update the static project dashboard/progress page |
| `upgrade-candidate` | query reveals a likely requirement, bug, stale source, or review issue |

## Inputs

- user question
- project root
- `.llm-wiki` root
- topic, module, requirement, bug, source, artifact, or dashboard hint
- optional current conversation context

## Outputs

Answer format:

```markdown
## Answer

## Project Context Pack

- project_root:
- wiki_pages_used:
- source_proxies_used:
- artifacts_used:
- related_requirements:
- related_bugs:
- related_modules:
- related_session_digests:
- cross_project_refs:
- project_graph_edges:
- project_graph_candidates:
- open_questions:
- confidence:

## Evidence

## Inference

## Possible Next Routes
```

Rules:

- Name the wiki pages used.
- State when evidence is insufficient.
- Do not expose sensitive raw content.
- Do not present inference as sourced fact.
- Treat Session Digests as recall context by default. They help recover what was discussed, but they are not confirmed project truth, scope, Flow Record, dashboard, or verification evidence unless selected items were explicitly promoted through Lifecycle Promotion. Prefer current code, current user confirmation, and current requirement/bug pages when conflicts exist.
- Keep the context pack small enough to feed into later discussion or lifecycle work.

Dashboard-refresh completion rules:

- Do not report completion if a child Flow Record appears only in evidence links or parent-card prose.
- Do not report completion if visible board cards and `dashboardData.flowRecords` disagree for any `flow_id`.
- Do not report completion if lane count badges do not match the visible cards in each lane.
- Do not report completion if dashboard-only changes would imply a stronger lifecycle status than the source Flow Record supports.

## Context Handoff

If the user upgrades after query, provide a handoff:

```markdown
## Context Handoff

- lifecycle_session:
- user_intent:
- active_sources:
- active_scope:
- read_only_scope:
- candidate_scope:
- excluded_scope:
- current_gate:
- requested_stage_or_bridge:
- constraints:
```

For pure query mode, `lifecycle_session` can be `none`.

## Return Handoff

Return:

```markdown
## Return Handoff

- stage_or_bridge_used: project-query
- result_summary:
- changed_assumptions:
- recommended_scope_changes:
- artifacts:
- verification_notes:
- lifecycle_updates_needed:
- next_gate:
```

For read-only query, `lifecycle_updates_needed` is usually `none`.

For dashboard refresh:

```markdown
## Dashboard Refresh

- dashboard_path:
- evidence_used:
- flow_records_used:
- updated_sections:
- unchanged_sections:
- unsupported_claims_downgraded:
- next_action:
```

## Boundaries

- Do not modify code.
- Do not create or update `.llm-wiki` by default.
- Ordinary cross-project lookup must not modify lifecycle state; writing a user-confirmed `.llm-wiki/registry.local.json` mapping, plus the matching `.gitignore` ignore lines when missing, is local resolver configuration per `cross-project-refs.md` Write Boundary.
- Do not write remote project wiki, source, config, registry, or reverse cross-refs.
- Do not create or update `project-graph/edges.md`, `project-graph/candidates.md`, or `cross-refs/index.md` in query mode; route registration to `project-maintain`.
- In `dashboard-refresh` mode, modify only `.llm-wiki/dashboard/progress.html`, `.llm-wiki/artifacts/index.md` dashboard metadata when needed, and `.llm-wiki/log.md`.
- In `dashboard-refresh` mode, do not create Change Briefs or mark plan/development/testing/archive done; show unmatched source/design docs as candidate or pending.
- In `dashboard-refresh` mode, do not repair Flow Record status. Route stale or contradictory Flow Record evidence to `project-finish`, `project-develop`, `project-fix`, or `project-review`.
- Do not create Change Brief, Bug Brief, or working-context unless the user explicitly asks to save or act.
- Do not deep-read every source or module.
- Do not treat stale wiki summaries as authoritative over source code, tests, or current user decisions.
- Do not route to full lifecycle just because a topic is development-related.

## Common Mistakes

- Treating every project question as `project-develop`.
- Creating Change Briefs for exploratory discussion.
- Ignoring `.llm-wiki` indexes and jumping straight to raw source files.
- Letting "real code first" override the query boundary. For project questions like "what exists here" or "how is this API called", use `project-query` first to recover requirement/source/working-context evidence, then inspect code only to verify current behavior.
- Returning a broad essay instead of a small context pack.
- Answering cross-service behavior from memory or inference instead of checking pin -> edge -> candidate and clearly labeling wiki-only or candidate-only evidence.
- Failing to name the wiki pages used.
- Hiding uncertainty when wiki evidence is stale or missing.
- Treating dashboard refresh as project finish.