diff --git a/.qwen/skills/bugfix/SKILL.md b/.qwen/skills/bugfix/SKILL.md index da558350072..db832fce6bc 100644 --- a/.qwen/skills/bugfix/SKILL.md +++ b/.qwen/skills/bugfix/SKILL.md @@ -103,6 +103,13 @@ with a verdict: After fixing valid issues, re-run unit tests and a quick verification sanity check. +## Step 7: Knowledge Closeout + +Run `/knowledge-lifecycle` before declaring the fix complete. Route only facts +introduced or changed by this work, update repository files that are in scope, +and leave GitHub mutations as proposals unless they are explicitly authorized. +Do not create a closeout artifact when no knowledge should persist. + ## Iteration Rules - If Step 4 fails, go back to Step 3, then re-run Step 4. diff --git a/.qwen/skills/feat-dev/SKILL.md b/.qwen/skills/feat-dev/SKILL.md index c1d7ab09814..0dcc43d81f0 100644 --- a/.qwen/skills/feat-dev/SKILL.md +++ b/.qwen/skills/feat-dev/SKILL.md @@ -131,7 +131,16 @@ After fixes, re-run unit tests and a quick E2E sanity check. Output: clean implementation with valid review findings addressed. -## Phase 8: Wrap Up +## Phase 8: Knowledge Closeout + +Run `/knowledge-lifecycle` before declaring the feature complete. Route only +facts introduced or changed by this work, update repository files that are in +scope, and leave GitHub mutations as proposals unless they are explicitly +authorized. Do not create a closeout artifact when no knowledge should persist. + +Output: canonical sources updated, or an explicit no-persistence result. + +## Phase 9: Wrap Up Skip unless the user asks. Create the branch, commit with Conventional Commits, push, and create a draft PR using the project PR template. Post E2E results as a diff --git a/.qwen/skills/knowledge-lifecycle/SKILL.md b/.qwen/skills/knowledge-lifecycle/SKILL.md new file mode 100644 index 00000000000..9a676e2884f --- /dev/null +++ b/.qwen/skills/knowledge-lifecycle/SKILL.md @@ -0,0 +1,111 @@ +--- +name: knowledge-lifecycle +description: Route Qwen Code repository knowledge to its canonical artifact + before, during, and after development work. Use for source-of-truth discovery, + knowledge closeout, durable knowledge promotion, or compact handoffs; do not + use it as a general note-taking or memory-dump workflow. +--- + +# Repository Knowledge Lifecycle + +Keep one canonical source for each fact. Other artifacts may summarize it only +when they also point to that source. + +## Modes + +- **Analyze-only** is the default for audits, reviews, and unclear write scope. + Report recommended updates without changing repository or GitHub state. +- **Explicit-write** applies when the user asked for an implementation or + documentation change and the proposed file updates are within that scope. + GitHub issues, pull requests, projects, and comments still require explicit + authorization before each workflow that mutates them. + +## Before Work + +1. Identify the task and affected paths. +2. Read the applicable `AGENTS.md` files and path-scoped rules. +3. Find current documentation, durable design records, and active GitHub or + implementation-plan context relevant to those paths. +4. Verify drift-prone claims against current code, tests, schemas, and + configuration before treating them as current facts. +5. Keep stable pointers to the sources you use. Do not copy their full content + into a new note. + +If sources conflict, report the conflict. Do not silently choose the newest file +or assume that current implementation overrides an accepted contract. + +## Route Knowledge + +| Knowledge | Canonical artifact | Update or retire when | +| ---------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- | +| Recurring repository or path-specific working agreement | The nearest applicable `AGENTS.md` or path-scoped rule | The agreement changes or no longer recurs | +| Current user or developer behavior | Current documentation | Shipped behavior changes; replace stale guidance | +| Durable rationale or a hard-to-reverse decision | Design document, RFC, or ADR | A later decision supersedes it; retain a pointer to the replacement | +| Active scope, ownership, progress, discussion, or blockers | GitHub issue, project, pull request, or active implementation plan | Work advances, closes, or is abandoned | +| Behavior that must remain true | Test, schema, lint rule, hook, or CI check | The invariant changes or is intentionally removed | +| Operational, migration, deprecation, or release knowledge | The relevant runbook or lifecycle document | The process or supported lifecycle changes | +| Short-lived investigation or handoff | A temporary `.qwen/` work artifact | Its stated expiry condition is met | + +Do not create a new artifact when an existing canonical source should be +updated. Do not add a manually maintained index merely to repeat the repository +tree. + +## During Work + +- Update only the artifacts that own changed facts. +- Use short summaries and stable pointers when another artifact needs context. +- Put dynamic status in GitHub, not in durable documentation. +- Put enforceable behavior in executable artifacts when practical; prose alone + is not the canonical source for an invariant. +- Keep investigations and transcripts temporary unless closeout identifies a + durable fact worth promoting. + +## Knowledge Closeout + +Before declaring work complete, inspect the actual diff and verified results, +then decide: + +1. Did current behavior change? Update current documentation and the executable + constraint that should preserve it. +2. Was a durable decision made? Update or add its design record and point from + any superseded record. +3. Did a working agreement prove recurring? Update the narrowest applicable + instruction file; do not promote task-specific advice. +4. Did active scope or status change? Propose the GitHub update and perform it + only with explicit authorization. +5. Was operational knowledge discovered? Update the owning runbook or lifecycle + document. +6. Is the information useful only for the current task? Leave it temporary or + discard it when its expiry condition is met. + +Report the result as a compact list of `source -> action -> pointer`. If no +knowledge should persist, say so instead of creating an empty closeout artifact. + +## Handoff + +When another agent or person must continue the work, provide only: + +- **Base commit:** the exact commit the verified state is based on. +- **Verified state:** what was checked and the observed result. +- **Blockers:** unresolved conditions, or `None`. +- **First next action:** one concrete action that can resume progress. +- **Expires when:** the condition that makes this handoff stale. +- **Canonical pointers:** links or paths to the owning issue, plan, design, + documentation, tests, or runbook. + +Do not copy specifications, issue discussions, or conversation history into the +handoff. + +## Routing Examples + +- **Small bug fix:** the regression test owns the invariant. Update user docs + only if documented behavior changed; keep progress in the issue or pull + request. +- **Behavior-changing feature:** current docs describe the shipped behavior, + tests enforce it, and a design record holds only durable rationale. +- **Durable design decision:** record the decision and alternatives in the + design document or ADR; mark an older decision as superseded with a pointer. +- **Long-running implementation:** keep ownership, progress, and blockers in the + active issue, project, or plan; handoffs point there instead of copying it. +- **Operational discovery:** update the runbook, migration, deprecation, or + release document that owns the process; do not bury it in a task transcript. diff --git a/docs/design/repository-knowledge-lifecycle-skill.md b/docs/design/repository-knowledge-lifecycle-skill.md new file mode 100644 index 00000000000..c876ff04991 --- /dev/null +++ b/docs/design/repository-knowledge-lifecycle-skill.md @@ -0,0 +1,45 @@ +# Repository Knowledge Lifecycle Skill + +Status: accepted for exploration in +[issue #9781](https://github.com/QwenLM/qwen-code/issues/9781). + +## Problem + +Qwen Code has instructions, current documentation, design records, active +GitHub state, executable constraints, and temporary work artifacts. Existing +workflows can update several of these, but they do not share a small decision +process for choosing the canonical destination of newly learned information or +retiring stale knowledge. + +The result can be duplicated facts, durable documents containing temporary +status, and handoffs that depend on conversation history. + +## Decision + +Add a project-level `knowledge-lifecycle` skill that: + +- discovers applicable sources before work and verifies drift-prone claims; +- routes each fact according to its lifecycle instead of creating a new store; +- defaults to analyze-only behavior and distinguishes authorized file edits + from separately authorized GitHub mutations; +- performs a lightweight closeout before feature and bug-fix workflows finish; +- defines a compact handoff containing state and canonical pointers rather than + copied specifications. + +The feature and bug-fix skills invoke the closeout at the end of their existing +verification and review phases. They keep ownership of implementation and +testing; the new skill owns only the routing decision. + +## Scope + +The first version changes project workflow instructions only. It does not add +production code, a generated index, a storage system, automatic journaling, or +automatic GitHub writes. It does not migrate existing design documents or +plans. + +## Validation + +Validate the new skill's frontmatter and structure with the skill validator, +then inspect each representative routing example against the decision table. +Review the workflow changes to confirm they add one bounded closeout step and +do not replace existing feature or bug-fix verification.