Learn skill for opencode - turns user corrections into durable guidance

learn.md

name	learn
description	Use when the user says "learn" or asks to remember a correction. Extract durable coding, workflow, or communication patterns from recent feedback and propose the right place to persist them.

Intent

Turn explicit user corrections into durable guidance so the same mistake is less likely to recur.

Use this skill only when the user explicitly asks to learn, remember, capture, or persist something.

Rules

• Do not persist one-off bug fixes, typos, formatting noise, already-documented rules, or guesses about ambiguous intent.
• Persist only reusable, specific rules that should change future behavior.
• This is a global skill: inspect the current project before assuming it has AGENTS.md, local README.md files, workflows, or memory support.
• Choose the narrowest durable location future agents will read: memory for personal preferences, project guidance for repo-wide rules, local docs for subsystem rules, workflow files for repeated processes.
• Keep the durable wording short. Prefer one scoped rule with rationale over a long section.
• If editing opencode skills, agents, plugins, or config, remind the user to restart opencode.

Learned Rules

• For frontend API clients, keep nested backend resources in matching nested client folders and re-export them as namespaces for bundled Api.Resource.Nested.actionApi usage; do not inline nested resource methods into the parent API object when the codebase has this module pattern.
• In WRAP API tests, preserve import sections by role: support helpers such as @/support belong in their own section before factories, while the primary service or module under test should be the final import so it stays visually distinct.
• In WRAP API query tests, exercise the query using only the parameters the query actually accepts; do not add unrelated narrowing filters in the test query to prove exclusion. Instead, run the broad query path and assert the complete returned set.
• In WRAP higher-level service tests, focus descriptions and assertions on the user-relevant effect the service provides, and make each test mutation-meaningful: deleting the code path named by the test should make it fail. Do not assert broad lower-level call mechanics or setup distinctions that belong to a sub-service or query test; assert only the delegated result, wrapper-owned errors, or the specific external side effect being named.
• In WRAP API tests, do not bundle unrelated values into expect({ ... }).toEqual({ ... }) to satisfy one-expect guidance. Use one direct assertion for the behavior under test, or split distinct behaviors into separate tests.
• In WRAP controller tests only, use the common response assertion pair: assert response.status with toEqual(...), then assert response.body as a whole with toEqual(...) using expect.objectContaining(...) for returned records.
• In WRAP API tests for missing preloaded associations, do not pass the instance returned directly from a factory when that factory uses associated records; refetch the record without includes so cached NonAttribute associations do not bypass the intended preload guard.
• In WRAP API tests, when arranging a record with associations loaded for the action under test, prefer await record.reload({ include: [...] }) over refetching the same record with findByPk; reserve findByPk without includes for missing-preload guard tests.
• In WRAP commit subjects, broad verbs like "align", "nest", "scope", or "move" must name the concrete namespace, target, and comparison point, e.g. "under workflow namespace to match workflow template routing", so the subject explains the outcome without relying on surrounding context.
• In Vue composables/components, name computed refs before passing them into another composable or helper; do not create computed(...) inline in an argument list because it hides the dependency and violates WRAP's named-reactive-value style.
• For WRAP UI QA and PR screenshots, set up and validate state only through user-visible UI actions unless the user explicitly authorizes backend/API/database setup; if the needed state cannot be reached through the UI, stop and ask rather than fabricating records.
• In WRAP controller tests, keep service mocks focused on the HTTP response path: prefer inline ServiceMock.perform.mockResolvedValue(...) or mockRejectedValue(...) in the Arrange block over mockImplementation(...) callbacks that inspect service arguments, unless those arguments directly affect the endpoint response under test.

Process

Step 1: Review history

Before proposing anything, read the git log of this gist repository to understand what has already been learned:

git -C <gist-repo-path> log --oneline --reverse

Then read the current content of learn.md in full. Compare the existing rules against the proposed learning to check for:

• Duplication: Is this rule already captured, even in different words?
• Contradiction: Does the new rule conflict with an existing one? If so, flag the conflict explicitly so the user can decide which to keep.
• Amendment: Does the new rule refine, narrow, or broaden an existing rule? If so, propose amending the existing rule rather than adding a parallel one.

Learning should be cumulative forward progress, not replacement or restatement.

Step 2: Propose the learning

Show the proposed learning unless the user explicitly asked to apply it without review:

Proposed learning:

• Rule: [specific behavior to apply]
• Scope: [where it applies]
• Rationale: [why]
• Persist in: [file, memory, or no durable location]
• I would not apply this when: [exceptions]
• Relationship to existing rules: [new | amends rule X | replaces rule X because Y]

Ask one concise clarification question if the rule, scope, or persistence location is ambiguous.

Step 3: Apply the learning

After confirmation:

1. Update this gist: Edit learn.md in the gist repository, commit, and push so the learning is version-controlled and traceable.
2. Update agent harnessing: Read any relevant project documentation (AGENTS.md, skill files, COMMITTING.md, workflow files) and update them to reflect the new rule. This is the "harnessing" step — a learning that only lives in this gist is not operational. It must be wired into the places where agents actually read instructions.
3. Make the smallest durable edit, preserve existing structure and tone, avoid duplicate guidance, and state exactly what changed.

Step 4: Publish

After committing to the gist repository, push the changes:

git -C <gist-repo-path> push

Self-Maintenance

This skill is itself version-controlled in a git gist. To update it:

1. Clone or pull the gist repository at https://gist.github.com/klondikemarlen/ff39b801f195d2219b06dfff294fc929
2. Edit learn.md in place
3. Commit with a descriptive message
4. Push to publish the update

Gists are git repositories, so the full commit history serves as the changelog. Each learn operation creates a new commit, making it easy to see how the skill evolved.

Worked Example

User correction: "Don't put detailed serializer rules in root AGENTS.md; keep AGENTS.md high-level and move serializer details near the serializer code. Learn that."

Step 1 — Review history: git log --oneline --reverse shows no prior rule about documentation sharding.

Step 2 — Proposed learning:

• Rule: Keep root assistant guidance focused on project-wide conventions; put subsystem-specific rules in nearby docs.
• Scope: Repositories with layered assistant documentation and local README files.
• Rationale: Local guidance stays closer to the code it governs and keeps root instructions readable.
• Persist in: Project AGENTS.md as a short sharding rule, and the relevant local README.md for the detailed serializer guidance.
• I would not apply this when: The repository has no local documentation structure or the rule truly applies across the whole project.
• Relationship to existing rules: New rule, no overlap.

Step 3 — Apply: Update learn.md in the gist with the new rule. Update AGENTS.md with the sharding principle. Update the local README.md where the serializer guidance should live.

Step 4 — Publish: Commit and push the gist repository.