Skip to content
Skills Library
Programming · Review & audit

agent-notes

/agent-notes

Use when deciding whether a Cherry Studio change needs an Agent Note, authoring or reviewing a Spec, recording a durable bug-fix decision, moving a note between proposed/implemented/rejected, or checking supersession and stacked Spec approval.

Licence
AGPL-3.0
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Use when deciding whether a Cherry Studio change needs an Agent Note, authoring or reviewing a Spec, recording a durable bug-fix decision, moving a note between proposed/implemented/rejected, or checking supersession and stacked Spec approval.

Original author description

Use when deciding whether a Cherry Studio change needs an Agent Note, authoring or reviewing a Spec, recording a durable bug-fix decision, moving a note between proposed/implemented/rejected, or checking supersession and stacked Spec approval.

How it works

  1. Classify the change
  2. Check the active tree first
  3. Spec-first stack
  4. Rejection
  5. Validation
Original SKILL.md headings · 45 lines, 628 words
SKILL.md preview
---
name: agent-notes
description: Use when deciding whether a Cherry Studio change needs an Agent Note, authoring or reviewing a Spec, recording a durable bug-fix decision, moving a note between proposed/implemented/rejected, or checking supersession and stacked Spec approval.
---

# Agent Notes

Read [the Agent Note rules](../../notes/README.md) before acting. Agent Notes preserve revisitable decisions; they do not replace current code, reference docs, issues, or PR discussion.

## Classify the change

Every human-authored PR declares an Agent Note or an explicit `N/A` reason. Automation-authored PRs (repository workflows and Dependabot) are exempt from this metadata requirement, not from normal validation.

The class names the decision's subject; it does not force every note to start as proposed. Choose the initial lifecycle from whether the target needs human agreement before implementation and whether the decision has already shipped.

- Use `N/A` for a local or mechanical edit that restores an existing contract without a durable tradeoff.
- Write an implemented `bug-fix` note in the same PR when the repair changes failure, compatibility, security, concurrency, atomicity, lifecycle, or another choice likely to be reversed without its root cause.
- A small, completed testing or other durable decision that does not meet the Spec-first threshold may enter its owning class as implemented.
- Start substantial feature, architecture, process, and simplification work with a proposed Spec.
- Start any class as proposed when behavior, ownership, ACs, alternatives, or risks need human agreement before implementation.

## Check the active tree first

Search by domain terms, mechanism names, paths, and rejected alternatives. Classify the result as new, same owner, partial supersession, or full supersession. Update the existing owner when possible. Partial supersessions stay active and cross-linked. Full supersession must preserve every unique rationale, alternative, consequence, and verification fact; deleting an old note requires explicit human approval.

There is no `archived/` lifecycle yet. Do not archive by age, merge status, moved code, or stale wording. Keep current owners factual; keep fully superseded notes active and cross-linked until a separately approved archive design provides active-first search, successor discovery, and matching gates.

## Spec-first stack

1. Create the bottom Spec branch and proposed bilingual note.
2. Give observable acceptance criteria contiguous `AC` IDs and a verification owner.
3. Create the Spec PR through `gh-create-pr`; `Spec PR` is `This PR`.
4. Inspect GitHub reviews and require an explicit `APPROVED` review whose commit id equals the current Spec head. Approval does not require merging.
5. After Approval, create implementation layers with `gh-stack`. Each PR links the Spec and lists its AC coverage.
6. A material behavior, ownership, AC, alternative, or risk change belongs on the Spec branch. Rebase upstack and require Approval again.
7. The final layer moves all three pair artifacts to `implemented/`, rewrites shipped reality in present tense, and maps every AC to actual evidence.

Before deciding step 7, run `gh stack view --json`. If it exits 2, follow the `gh-stack` skill's remote-discovery procedure; missing local metadata does not prove the PR is standalone. For a stack, inspect the current layer and every downstack implementation PR, then aggregate only ACs backed by verification that was actually run. Intermediate layers keep the note proposed; only the final layer whose cumulative evidence covers every approved AC performs the transition. Do not infer finality from branch order alone.

After `gh stack sync`, rerun `pnpm change:scope` against every live PR base and rerun only checks invalidated by the rewritten scope. A successful sync is not validation.

## Rejection

Only an explicit human decision moves a proposed note to rejected. Discussion, silence, and `CHANGES_REQUESTED` do not. Preserve a rejected note only when its evidence prevents a plausible repeated mistake; otherwise close the unmerged exploration without adding repository noise. Stop and close any implementation layers after rejection.

## Validation

For a lifecycle move, run `pnpm agent-notes:check-transition --base <verified-spec-ref>` in addition to `pnpm docs:check-notes`, the scoped pairing write/check, `pnpm docs:check`, and `git diff --check`. The transition checker validates the declared direction and AC mapping; it never decides rejection or stack completion. Report only evidence actually run.

Versions

RepositoryScoreLicence
This page · cherryhq/cherry-studio90AGPL-3.0
BoogonClothman/boogon-agent-notes100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 3af80b69c9ed (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90find-simplifications
    Use when asked to find or plan Cherry Studio cleanup, simplification, refactoring, dead-code removal, duplicated state removal, unnecessary APIs, speculative generality, or library replacements, especially when the result should become evidence-backed proposed Agent Notes.
  • 100cherry-regression-test
    Run Cherry Studio critical-path system regression tasks through the repository-owned Playwright E2E workflow. Use for full regression, release acceptance, development-branch system validation, or a named cherry-regression-test task on GitHub-hosted macOS and Windows runners.
  • 100pg-archive-agent-notes
    Use when adding, auditing, pruning, archiving, restoring, or reviewing Agent Notes in this repository; checks every new note for superseded active records, deletes records only about small UI or purely mechanical changes, classifies other implemented notes by future decision…
  • 95release-cherry-pick
    Cherry-pick merged PRs labeled for a release branch into that branch, then open a PR and apply the cherry-pick-done label. Use when asked to "cherry-pick PRs for release/X.Y.Z", "pick PRs to release branch", or "cherry-pick labeled PRs".
  • 90hotfix
    Cherry-pick a fix to a release branch and optionally tag it. Use when backporting a bug fix to an older release, creating a patch release quickly, or moving a fix from main to a release branch.
  • 100note-it
    Capture implementation notes after code implementation and review/fix. Records design decisions, deviations, tradeoffs, and open questions to docs/issue#XXXX.html. Triggers on: /note-it, 记录笔记, implementation notes.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.