Learnings and Knowledge Base

Learnings teach CodePeel your codebase conventions, suppress false positives, and refine review quality over time. Every learning is stored per-repository and applied to future reviews, making analysis increasingly relevant to your team's patterns and preferences.

---

Overview

The learnings system is CodePeel's memory. When you tell it "we use effect-ts for error handling, not try/catch" or "stop flagging console.log in debug files", that instruction is saved and applied to every future review for that repository. Over time, this eliminates recurring false positives and ensures the AI checks for your team's specific conventions.

Each learning has a feedback type determining how it's used during reviews:

• Confirmed rules (correct) — injected as team preferences the AI enforces
• Suppression rules (incorrect, ignore) — injected as false positive corrections the AI avoids flagging

Three input methods feed into the same review pipeline:

1. PR comment commands (@codepeel learn:, @codepeel ignore:)
2. VS Code extension feedback buttons (thumbs up/down, "Learn: Never flag this")
3. .codepeel.yml expert_rules for version-controlled team standards

---

How It Works

Injection into Reviews

When CodePeel reviews a PR or processes an IDE review:

1. Learnings loaded for the repository
2. Rules split by feedback type:
   • correct → injected as "TEAM PREFERENCES & LEARNED RULES"
   • incorrect/ignore → injected as "FALSE POSITIVE CORRECTIONS (do not flag these patterns)"
3. Sanitization applied — descriptions capped at 500 chars
4. AI considers both sections alongside standard analysis

Data Model

Each LearnedRule document contains:

Category Auto-Detection

If no explicit category set, learnings are categorized by keywords:

---

Adding Learnings

Via PR Comment (Fastest)

Preferences — enforce a convention:

@codepeel learn: Always use Zod schemas for API request validation
@codepeel learn: We use effect-ts for error handling, not try/catch
@codepeel learn: The src/generated/ directory is auto-generated — never flag issues there

Suppressions — stop flagging a pattern:

@codepeel ignore: Don't flag TODO comments as issues
@codepeel ignore: The console.log in src/lib/debug.ts is intentional
@codepeel ignore: We intentionally use any type in migration scripts

Rules saved immediately. CodePeel replies with confirmation. learn: implies "enforce this"; ignore: implies "stop flagging this."

Via Natural Conversation

CodePeel detects learning intent from conversational comments. No special syntax needed:

• "We use console.log for debugging, stop flagging it" → saved as ignore rule
• "This is fine, we handle auth at the middleware level" → saved as preference
• "Actually nested try-catch is our pattern here" → saved as preference

When AI detects teaching intent, it saves the rule and includes a collapsible confirmation showing what was learned.

Via VS Code Extension

Feedback buttons on inline comments:

• Thumbs up → confirm finding is correct (reinforces pattern)
• Thumbs down → mark as incorrect (creates suppression rule), optional reason
• Mortar board icon → "Learn: Never flag this" (permanent suppression with finding context)

Learnings sync with GitHub PR reviews (same backend storage).

Via .codepeel.yml (Version-Controlled)

For team-wide conventions:

expert_rules:
  - "Use functional components with hooks, not class components"
  - "All database queries must use the repository pattern"
  - "API responses follow JSend specification"
  - "Never use any type — use unknown and narrow"

See Configuration for expert_rules vs rules (custom regex) comparison.

---

Managing Learnings

Dashboard: Learnings Page

1. Select repository from dropdown
2. View all active learnings (paginated)
3. Each shows description, feedback type, category, creation date
4. Change feedback type with buttons
5. Delete learnings no longer needed

Dashboard: Knowledge Base Page

Aggregate view across all repositories:

• Learning growth chart (line chart over time)
• Pattern category breakdown (pie chart)
• Learnings per repository (top 10 by count)
• Recent learnings (last 10 across all repos)
• Date range filter (7d/30d/90d) and repository filter

Feedback Actions

Changes take effect on next review — no cache expiration wait.

Deleting a Learning

The API only supports deleting one learning at a time. There is no ruleId=all shortcut:

DELETE /api/learnings?repoId=owner/repo&ruleId=<specific-rule-id>
Authorization: Bearer <token>

To delete all learnings for a repository, call this endpoint once per rule ID (list them first via GET /api/learnings?repoId=...). For team-wide resets, prefer moving conventions to expert_rules in .codepeel.yml so they survive database resets.

---

How Learnings Affect Reviews

Confirmed Rules (correct)

Injected as "TEAM PREFERENCES & LEARNED RULES". AI actively looks for violations.

Example:

• Learning: "All async functions must have error handling"
• Effect: AI flags async functions without try/catch or .catch()

Suppression Rules (incorrect/ignore)

Injected as "FALSE POSITIVE CORRECTIONS (do not flag these patterns)". AI avoids flagging matching patterns.

Example:

• Learning: "Don't flag TODO comments as issues"
• Effect: AI skips findings about TODO comments

Interaction with expert_rules

Both injected into same prompt:

1. expert_rules loaded from config file
2. Confirmed learnings appended after
3. Suppression learnings in separate "FALSE POSITIVE CORRECTIONS" section

Conflicts resolved by AI judgment — more specific instruction usually wins.

---

API Reference

The learnings system is accessible via REST API for programmatic management.

List Learnings

GET /api/learnings?repoId=owner/repo&page=1&pageSize=20
Authorization: Bearer <token>

Returns paginated learnings for a repository. Without repoId, returns all learnings for the user.

Add a Learning

POST /api/learnings
Authorization: Bearer <token>
Content-Type: application/json

{
  "repoId": "owner/repo",
  "action": "add",
  "rule": {
    "pattern": "comment-command",
    "description": "Use parameterized queries for all database access",
    "feedbackType": "correct",
    "pathPattern": "src/api/**"
  }
}

Update Feedback Type

POST /api/learnings
Authorization: Bearer <token>
Content-Type: application/json

{
  "repoId": "owner/repo",
  "action": "feedback",
  "ruleId": "abc123",
  "feedbackType": "incorrect"
}

Delete a Learning

DELETE /api/learnings?repoId=owner/repo&ruleId=abc123
Authorization: Bearer <token>

Authentication

• The MCP server and VS Code extension manage learnings with cpk_ API tokens.
• For full programmatic access (list, delete), sign in to the dashboard and use the API there.

---

Best Practices

Add Learnings Early

The sooner CodePeel knows your conventions, the fewer false positives. On first install, spend a few minutes adding key conventions — pays off immediately on next review.

Be Specific

Vague learnings like "be careful with databases" have little effect. Specific learnings give the AI a clear standard:

Good examples:

• "Use logger.info() from @/lib/logger instead of console.log"
• "Error responses must include a code field matching our error catalog"
• "React components in src/components/ui/ must accept a className prop"

Use Ignore Rules for Known Patterns

When you see a false positive, suppress it immediately rather than dismissing repeatedly. One @codepeel ignore: The console.log in debug utilities is intentional prevents the same false positive on every future PR.

Review Periodically

As codebase evolves, some learnings become outdated. Visit Learnings page periodically to remove rules that no longer apply. Outdated learnings can confuse the AI and reduce quality.

Combine Methods

Use expert_rules in .codepeel.yml for team standards needing version control and PR review. Use learn: commands for ad-hoc rules and false positive suppression. Both feed into the same pipeline.

---

Troubleshooting

Learning Not Applied to Reviews

1. Verify learning exists in Learnings page for correct repository
2. Check feedback type — incorrect/ignore suppress, correct enforces
3. Ensure repository ID matches exactly (owner/repo)
4. Learning may be too vague — make it more specific

"Learning Failed" Error in VS Code

• Authentication token expired → sign out and back in
• Network connectivity issue
• Repository not identified → ensure workspace is Git repo with remote

Learnings from One Repo Not in Another

Learnings are scoped per repository. For cross-repo conventions, add to each repo individually or use expert_rules in .codepeel.yml (shareable via common config).

Too Many Learnings Diluting Quality

If review quality degrades with many learnings:

1. Go to Learnings page
2. Filter by repository
3. Delete outdated/overly broad rules
4. Keep rules specific and actionable

No hard limit, but reviews have finite context. 100+ learnings may reduce attention to each rule.

PR Comment Command Not Working

1. Verify GitHub App installed on repository
2. Check chat.auto_reply not false in Configuration
3. Comment must be on a PR (not an issue)
4. Must mention @codepeel (case-insensitive)

---

FAQ

Do learnings sync between VS Code and GitHub PR reviews? Yes. Same storage regardless of creation source. A learning added in VS Code is immediately available for the next GitHub PR review, and vice versa.

Is there a limit on learnings? No hard limit. Each description capped at 500 chars in prompt. Total prompt has finite context. Optimal: 10–50 active learnings per repository. Prune outdated rules periodically.

Can I export/import learnings between repositories? Not directly via UI. Use API to list from one repo and create in another. For team-wide conventions, use expert_rules in .codepeel.yml (copiable across repos).

Difference between learnings and custom rules? Learnings are AI-interpreted preferences stored in database, guiding AI judgment. Custom rules (rules field in .codepeel.yml) are deterministic regex matchers producing findings on pattern detection. Learnings = flexible/contextual; custom rules = exact/deterministic.

Do learnings affect MCP server reviews? Yes. MCP reviews load learnings for the repository (via repo parameter) and apply them in the same way.

Can I see which learnings influenced a specific review? Not directly in current UI. Learnings injected as context but review results don't tag which learning caused/suppressed a finding. Infer influence by comparing findings before/after adding a learning.

---

Examples by Use Case

Suppressing Framework-Specific Patterns

@codepeel ignore: In Next.js, exporting generateMetadata is correct — it's a framework convention
@codepeel ignore: Flutter's build() method returning deeply nested widget tree is normal
@codepeel ignore: Django's Meta class inside models is intentional, not a naming issue

Enforcing Team Architecture Decisions

@codepeel learn: All API calls must go through apiClient in src/lib/api.ts — never use fetch() directly in components
@codepeel learn: State management uses Zustand stores in src/stores/ — do not use React context for global state
@codepeel learn: Database migrations must be idempotent — always use IF NOT EXISTS and IF EXISTS guards

Correcting False Positives About Intentional Patterns

@codepeel ignore: The empty catch block in src/lib/graceful-shutdown.ts is intentional — we want to swallow errors during shutdown
@codepeel ignore: Using eval() in src/plugins/dynamic-loader.ts is intentional for plugin sandboxing
@codepeel ignore: The circular dependency between User and Organization models is intentional — they reference each other

Teaching Project-Specific Terminology

@codepeel learn: In our codebase, "vault" refers to the encrypted credential store, not a physical vault
@codepeel learn: "Hydration" in our context means populating cache from database on startup, not React hydration

---

Learning Lifecycle

Creation

Created via PR comment, VS Code extension, or API. Available for the next review.

Active Use

On every review, all repository learnings are loaded. Confirmed rules guide enforcement; suppression rules guide avoidance.

Feedback Refinement

Over time, a learning may be too broad/narrow. Change type via dashboard feedback buttons:

• correct causing false positives → change to ignore
• ignore that should be enforced → change to correct

Retirement

When no longer relevant (codebase changed, convention abandoned), delete from Learnings page. Outdated learnings can confuse AI and reduce quality.

Migration to expert_rules

If a learning proves valuable for the team, migrate to expert_rules in .codepeel.yml. Makes it version-controlled, visible in code review, and survives database reset.

---

---

Generating .codepeel.yml from Learnings

The init-config CLI command generates a .codepeel.yml including your learnings as expert_rules:

npx -y github:codepeel/mcp-server init-config

Fetches dashboard settings and recent learnings, writes to YAML. Useful for:

• Bootstrapping config with existing learnings
• Making learnings version-controlled
• Sharing learnings with team members without database access

Generated file includes up to 20 learnings as expert_rules. Edit after generation to refine before committing.

---

Related Documentation

• Configuration — expert_rules and .codepeel.yml reference
• VS Code Extension — Feedback buttons and "Learn: Never flag this" command
• MCP Server — How learnings apply to programmatic reviews