| name | zl-debug |
| description | Zhulong native debug command for Codex. Use when the user invokes $zl-debug or asks to debug a defect through Zhulong Project Intelligence Kit with project state, task/source evidence, optional documents, code-map context, verification, and evidence writeback. |
Zhulong Debug
This is the Codex runtime entrypoint for $zl-debug.
Invocation
- Treat all user text after
$zl-debug as ZL_ARGS.
- Preserve
$zl-debug in user-facing notes.
- Treat GSD commands such as
$gsd-debug as reference design only.
- When suggesting next commands to the user, suggest
zl-* commands, never
$gsd-* commands.
Required Flow
- Resolve the project root from the current working directory.
- Run the deterministic Zhulong preflight:
{{ZL_CLI}} workflow run debug --target "$PWD" "<ZL_ARGS>"
If the current user message explicitly requests a fix, implementation, patch,
or repair, append --intent fix. Otherwise omit it and keep the workflow
diagnose-only.
- Read the generated
.planning/context/*debug*.md packet and matching
.planning/context/handoffs/*debug*-HANDOFF.md.
- Establish expected behavior from the request, active records, source, and
tests. Query
.planning/knowledge/ or local documents only when relevant
sources exist; use RAG only when rag_backend is not none and approved.
- Check code-map context before risky edits:
zl-graph-status, zl-graph-query, .planning/graphs/, and source reads.
- Follow
core/workflows/debug.md as the Zhulong native workflow contract.
- Default to diagnose-only. Stop after the verified diagnosis unless the user
explicitly requests a fix or a matching Goal authorization permits
debug_fix; only then implement after root cause and impact are clear.
- Verify with focused tests, source checks, logs, or manual reproduction.
- If structural relationships changed and direct graph refresh is approved,
run
zl-graph-build --run and inspect zl-graph-diff.
- Record durable evidence with
zl-evidence-record when the work is non-trivial.
Use --writeback, --debug, or --issue to append the evidence summary
to the active backend record when one exists.
Fallback
GSD is reference design only. Continue inline using the same Zhulong packet:
diagnose, plan, and verify the diagnosis. Implement only with explicit fix
intent or a matching Goal grant, then verify and write evidence. Keep $gsd-*
out of user-facing invocation instructions.
