Skip to content

docs(users): add evidence-based-conclusions recipe to common workflows - #8702

Merged
wenshao merged 2 commits into
QwenLM:mainfrom
Dmatut7:docs/evidence-based-conclusions-recipe
Aug 29, 2026
Merged

docs(users): add evidence-based-conclusions recipe to common workflows#8702
wenshao merged 2 commits into
QwenLM:mainfrom
Dmatut7:docs/evidence-based-conclusions-recipe

Conversation

@Dmatut7

@Dmatut7 Dmatut7 commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

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

  • Docs-only change, 37 insertions.
  • prettier --check passes on both files (repo's prettier 3.5.3, same as CI's lint.js --prettier).

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
@qwen-code-ci-bot

qwen-code-ci-bot commented Aug 7, 2026

Copy link
Copy Markdown
Collaborator

Qwen precheck requires maintainer approval before automated triage/review.

Head SHA: 5dfb4f58b5281d3e13349c4efc65710bbdb08754

Reason:

  • prompt_injection:system_prompt

A maintainer with write access can inspect the PR and manually request a run with @qwen-code /triage or @qwen-code /review. A new push requires a fresh precheck.

@wenshao

wenshao commented Aug 8, 2026

Copy link
Copy Markdown
Collaborator

@qwen-code /review

@qwen-code-ci-bot qwen-code-ci-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Comment thread docs/users/common-workflow.md Outdated
Comment on lines +597 to +601
| 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 |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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).

Suggested change
| 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)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 wenshao left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed. Suggestions are inline.

— deepseek-v4-flash via Qwen Code /review (v0.21.7)

Comment on lines +579 to +581
**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:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

Suggested change
**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)

@wenshao

wenshao commented Aug 29, 2026

Copy link
Copy Markdown
Collaborator

@qwen-code /review

@github-actions

Copy link
Copy Markdown
Contributor

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 qwen-code-ci-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found. LGTM! ✅

— qwen3.8-max via Qwen Code /review (v0.22.3)

@wenshao
wenshao added this pull request to the merge queue Aug 29, 2026
Merged via the queue into QwenLM:main with commit 7d9ec83 Aug 29, 2026
88 checks passed
@Dmatut7
Dmatut7 deleted the docs/evidence-based-conclusions-recipe branch August 29, 2026 23:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants