Conventions (team memory) | kanman documentation

Every team has rules that are written down nowhere: use the shared money formatter, never call the payment API from a controller, put feature flags in one file. People learn them in code review. kanman learns them the same way, and unlike a black box, it shows you what it learned and lets you change it.

How kanman learns

During a run, kanman keeps a scratchpad. At the end it writes a short retrospective: what worked, what it had to redo.
In review, the independent reviewer run raises objections, for example “use the shared money formatter instead of toFixed”.
After each attempt, lessons from the retrospective and the reviewer’s objections are stored and tagged with the areas of the repository they apply to, such as src/invoices.
Every night, kanman groups the objections of the last 90 days. A group becomes a convention once it has at least three objections from at least two different runs. An objection that matches an existing convention strengthens it instead; a retired convention is never created again.
In future runs, pinned conventions are always part of the executor’s brief, active ones when they apply to every area or to an area the story touches. Recent lessons and objections on the same areas come along too.

How kanman keeps its memory current

kanman only learns from work that was merged and passed every check, and it remembers where in your code each lesson and convention came from.

Checked before every use. Before a run, kanman looks at that code on the current branch. If the code a lesson points to has been rewritten or removed, kanman leaves the lesson out of the run and checks it again on a later one.
Retired when unused. A lesson or convention kanman has not needed for four weeks while the team was working retires on its own. Retired conventions appear under Retired, where Restore brings them back. Pinned conventions and conventions you edited never retire on their own, and a team that pauses for a while keeps everything.

Learning from your feedback

kanman also learns from what you correct directly, not only from repeated review findings:

a draft you reject, with the reason you give in the line that appears under it (Why not? I’ll learn from it)
acceptance criteria you rewrite in a draft before you approve it
changes you request in the review of kanman’s own pull or merge requests
maintenance proposals you decline
answers you give to kanman’s questions

kanman reads each correction and decides whether it is a rule for future work or a one-off fix. A rule becomes a convention right away, and kanman says so in the team’s conversation, for example “From now on I’ll write the acceptance test with the tenant stub, as Anna asked in PU-43.” Nothing is learned silently: the card under the message names where the rule came from, with a link to the story, the draft, the pull or merge request comment or the decision, and offers Don’t learn this. One tap retires the rule, and kanman does not learn it again from the same kind of feedback.

A correction that repeats a convention the team already has strengthens that convention instead of creating a second one; the convention’s page lists it under Where this came from with its source. Rules learned from feedback also shape the stories kanman drafts, not only its runs.

Workspaces that run everything on their own runners learn the same way: the runner reads the feedback with the team’s model access.

Approaches kanman learned

Rules say what to avoid. kanman also keeps how it solved a recurring kind of task, so the next run follows the way instead of searching for it again: where the coverage threshold of your pipeline really lives, how a dependency update is done in your repositories, which check proves the fix.

Learned only from verified work. After a run that was merged, passed every check and needed some searching, a rework round or a correction by a person, kanman writes down the approach: when it applies, the steps, known pitfalls and how to check the result. Each step names the file and lines it was learned on, and the page lists the runs it came from.
Tried once more before it counts. A new approach is marked New until it has worked in one more run, or until you pin it.
Used where it fits. When a story matches an approach, its plan builds on it and the run follows its steps. The run page says so, for example Following my approach for coverage failures, worked 6 of 7 times, with a link to the approach. Like every lesson, an approach is checked against the current code before each use and left out when the code it points to is gone.
Proves itself. Each approach counts how often it worked and how often it needed rework, and compares how often runs were right on the first try with it and without it. When an approach keeps failing, kanman revises it from the failing run and says so once in the team’s conversation, for example “I updated my approach for coverage failures: the threshold lives in .gitlab-ci.yml, not the Makefile.” If it cannot be fixed, kanman stops using it. Approaches nobody needed for four weeks retire on their own, like lessons.
Your repository’s own skills. If a repository already contains skills for coding agents (for example in .claude/skills/), kanman reads them and lets the coding agent use them. It never changes them; what kanman learns stays separate.

Approaches appear in the same list as the rules, marked with a steps icon, with their steps and how often they worked. Open one to see its steps, pitfalls, the check it runs, how it worked and its versions with the reason for each change.

Use in the whole workspace

A rule or an approach starts in the team that learned it. Use in the whole workspace makes it apply to every team of your workspace; Undo right after takes it back. When an approach worked in several repositories or teams, kanman suggests this once in the team’s conversation, and one tap on Use in the whole workspace confirms it. Entries used in the whole workspace show Whole workspace in every team’s list. What kanman learns is never shared with other workspaces.

Rules that prove themselves

A rule is only worth keeping if the review finding behind it stops coming back. kanman checks this for every rule it learned.

Effect you can see. In the list, a rule says Not raised again since kanman learned it, or how often the same finding came back since.
Rewritten when it does not land. When the finding keeps coming back on later runs that had the rule in their brief, kanman rewrites the rule more concretely, from the findings that came back, and says so once in the team’s conversation. If two rewrites in four weeks do not help, kanman stops using the rule; you find it under Retired. Rules you pinned or edited are never rewritten or retired by kanman.
Checked automatically. When a rule forbids something visible in a single line of code, for example a call your team replaced with a shared helper, kanman turns it into an automatic check. It first only watches: once the check has caught the finding the reviewer raised, without a false alarm, it applies to every run and the coding agent fixes such a line before it finishes. A check that flags work your reviewers let through is dropped again; the rule stays. These rules show Checked automatically. The checks only ever add to the checks of your team, they never replace or loosen one.
Duplicates merged. Every night kanman merges rules or approaches that say the same thing into one, with all the evidence of both. Nothing is deleted: the merged entry stays under Retired.
Contradictions asked once. When two things kanman learned contradict each other, kanman asks your team once which one holds, as a decision. The one you keep is pinned, the other retired. If both hold in different cases, kanman leaves them as they are and never asks about the pair again.

Approaches for planning and from your pipeline

Outcome plans. When kanman plans an outcome with several stories, it also builds on the approaches that match those stories, and the plan names the ones it used.
Your pipeline and scripts. Before a run, kanman reads how the repository checks its work: the jobs of its CI configuration, the test, lint and build scripts and coverage thresholds. The coding agent gets that list, with the file and line each entry comes from, so it runs the same checks your pipeline runs. kanman only reads these files.

Keeping AGENTS.md current

Many repositories keep instructions for coding agents in an AGENTS.md file. Under Settings, Knowledge, below the conventions, Propose updates to AGENTS.md lets kanman offer what it learned there too. It is off until you turn it on.

When it is on, kanman proposes, as one decision, to write the rules and approaches that proved themselves for a repository into a marked section of its AGENTS.md. The decision shows the exact text. If you approve, kanman files a small story; its merge request follows your team’s usual rules, and a change to agent instructions always waits for a person to merge it. kanman never merges it itself. The same content is never proposed twice, and there is at most one open proposal per team.

Conventions you can see

Open the team, then Settings, Knowledge. The page first shows the sources kanman reads for the team (see Team context and connectors), then the conventions kanman learned. Old links to the former Conventions page land there. The conventions list shows active and pinned conventions (pinned first) under Active, and retired ones under Retired. Each convention shows:

the rule in one sentence, for example Format money with the shared formatter
where it applies (Applies to: repository areas, or every area)
its source, for example 3 review findings; its detail page shows them flowing into the rule under Where this came from and lists them with links to the runs
its status: active, pinned or retired

Team settings, Knowledge: the learned conventions listing a learned rule with its review findings and a learned approach with its steps and how often it worked, each with Pin, Use in the whole workspace and Retire

Your rules

Above the conventions, Your rules lists the answers you turned into rules with Apply this to similar cases (see Answers that become rules). Each rule shows where it came from (for example “From your answer on INT-172, 9 Oct”), whether it applies to one goal, the team or the whole workspace, and how often kanman applied it. Retire stops it. A rule you overturned twice within 30 days waits for Keep it. Your rules are your word: kanman never replaces them with something it learned.

What you can do with a convention

Action	Effect
Pin	Puts the convention into every run of the team, whatever area the story touches. Unpin makes it a normal active convention again
Edit	Rewrites the rule in your words. The lineage to the original runs stays
Retire	Removes it from future runs. It moves to the retired list, where Restore brings it back
Use in the whole workspace	Makes a rule or an approach apply in every team of your workspace. Undo right after takes it back

Every change is recorded in the audit log as convention_changed with your name.

Why it matters

kanman gets better at your codebase every week, and you can see what it learned. Reviewers stop repeating the same comment, and new rules are visible to everyone instead of living in one person’s head.

What is not stored

Conventions hold rules and short excerpts from review findings, not copies of your code. They belong to the team and are deleted with it. See Retention and deletion.