docs(users): add evidence-based-conclusions recipe to common workflows - #8702
Conversation
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
|
Qwen precheck requires maintainer approval before automated triage/review. Head SHA: Reason:
A maintainer with write access can inspect the PR and manually request a run with |
|
@qwen-code /review |
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Reviewed. Suggestions are inline. Not reviewed: reverse audit — stopped before round 2 by the review time budget. Not reviewed: verification and reverse audit — each ran and opened its brief, but neither was launched with the prompt the CLI built — the launches were written by hand, so the posted findings cannot be counted as verified, and what the agents were actually asked is not what this skill certifies.
— qwen3.8-max via Qwen Code /review (v0.21.7)
| | File | Use when | | ||
| | ------------------------- | ---------------------------------------------------------- | | ||
| | `QWEN.md` in project root | The policy applies to the whole team (commit it) | | ||
| | `~/.qwen/QWEN.md` | The policy applies to you personally, across all projects | | ||
| | `.qwen/QWEN.local.md` | The policy is personal to you and specific to this project | |
There was a problem hiding this comment.
[Suggestion] This scope table restates the QWEN.md location→scope mapping that already exists in the "Where to create QWEN.md" table in docs/users/features/memory.md (same three files, same semantics). The two copies have already diverged: this table omits the "(keep out of git)" caveat that memory.md carries for .qwen/QWEN.local.md, so a reader who follows only this recipe could commit a personal policy file that memory.md explicitly warns must stay out of git. Since the section already links to memory.md twice, the canonical table is one click away.
Failure scenario: the memory-file scopes or their semantics change → only one of the two tables gets updated → the two pages silently give users inconsistent scope guidance (the divergence is already present in this PR).
| | File | Use when | | |
| | ------------------------- | ---------------------------------------------------------- | | |
| | `QWEN.md` in project root | The policy applies to the whole team (commit it) | | |
| | `~/.qwen/QWEN.md` | The policy applies to you personally, across all projects | | |
| | `.qwen/QWEN.local.md` | The policy is personal to you and specific to this project | | |
| See [Where to create QWEN.md](./features/memory.md#where-to-create-qwenmd) for which file applies to whom — commit the project-root `QWEN.md` copy so the policy covers the whole team. |
If you prefer to keep the inline table for recipe self-containment, restoring the "keep out of git" caveat here would also resolve the divergence.
— qwen3.8-max via Qwen Code /review (v0.21.7)
There was a problem hiding this comment.
Applied the suggested change in 5dfb4f5 — removed the duplicated table and linked to the canonical "Where to create QWEN.md" section in memory.md instead.
…edback Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
wenshao
left a comment
There was a problem hiding this comment.
Reviewed. Suggestions are inline.
— deepseek-v4-flash via Qwen Code /review (v0.21.7)
| **1. Add a verification policy to your project QWEN.md** | ||
|
|
||
| Put this template in `QWEN.md` at your repository root and commit it, so the policy applies to the whole team: |
There was a problem hiding this comment.
[Suggestion] Step 1 unconditionally mandates committing the policy to the repository root "so the policy applies to the whole team", while step 2 ("Choose the right scope") presents scope as a choice only after placement is already mandated — and its own body repeats the same repo-root mandate. — Failure scenario: a reader who wants the policy only for themselves (the ~/.qwen/QWEN.md / .qwen/QWEN.local.md scopes the linked table offers) follows the steps top-to-bottom: step 1 tells them to commit a team-wide file before step 2 ever mentions alternatives, so the policy lands in a committed, team-wide file against the reader's intent.
| **1. Add a verification policy to your project QWEN.md** | |
| Put this template in `QWEN.md` at your repository root and commit it, so the policy applies to the whole team: | |
| **1. Choose the right scope** | |
| See [Where to create QWEN.md](./features/memory.md#where-to-create-qwenmd) for which file applies to whom. | |
| **2. Add the policy to the file you chose** | |
| Put this template in the file from step 1 and commit it: |
— deepseek-v4-flash via Qwen Code /review (v0.21.7)
|
@qwen-code /review |
|
Qwen Code review request accepted. Review is running in workflow run. A command-triggered review is not listed under the checks of this PR; the result is posted here as a review when it finishes. |
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
No issues found. LGTM! ✅
— qwen3.8-max via Qwen Code /review (v0.22.3)
Summary
Implements the "docs recipe" that the triage of #8701 recommended as the first step.
docs/users/common-workflow.md: new section Enforce evidence-based conclusions — a copy-pasteable QWEN.md verification-policy template (verify before concluding, verify the full chain, treat transcripts as leads not facts, troubleshooting order, 100% evidence rule in reviews), plus scoping guidance (team vs personal) and tips for keeping the policy effective.docs/users/features/memory.md: cross-reference to the template from "What to put in QWEN.md".Why
The triage on #8701 confirmed the problem is real but noted that baking the rules into the default system prompt would tax every session's context (#6097), and an opt-in mode would add config surface for behavior that is hard to measure. It stated "a docs recipe is a reasonable first step either way" — this PR is exactly that step: it makes the pattern shareable without changing anyone's defaults.
The rules are adapted from a production retrospective of a multi-agent deployment; the failure-mode stats are in #8701.
Validation
prettier --checkpasses on both files (repo's prettier 3.5.3, same as CI'slint.js --prettier).