Dosu LogoDosu Logo
Ask
Join our Discord
Organization avatar
bluefinPublic
Bluefin
Documentsbluefin
skill-improvement
skill-improvement
Type
External
Status
Published
Created
Jun 13, 2026
Updated
Oct 27, 2026
Updated by
Dosu Bot
Source
docs/skills/skill-improvement.md

Skill Improvement Mandate — dakota-iso#

Every agent session produces two outputs:

  1. The work — the PR, fix, or improvement
  2. The learning — what a future agent should know

Output 1 without Output 2 leaves the factory no smarter. The loop only compounds if agents write back.

Contents#

  • Before You Mark Work Complete
  • What Counts as a Learning Worth Writing Back
  • Where to Write It
  • Format
  • Committing
  • See Also

Before You Mark Work Complete#

Run this checklist before opening a PR for review or marking an issue done:

  • Did I discover any workaround, non-obvious pattern, or convention?
  • Is there a skill file for the area I worked in?
  • If yes — did I update it?
  • If no — did I create one in docs/skills/?
  • Is the skill file committed in this same PR? (Not a follow-up. Same PR.)

If all five are checked, you're done. If any are unchecked, finish them first.


What Counts as a Learning Worth Writing Back#

Write it:

CategoryExample
Upstream bug workaround"installer_channel=dev regressed fisherman overlay storage — use stable until tuna-os/fisherman#38 resolves"
Non-obvious correctness requirement"Build the payload with podman build from a FROM-only Containerfile, not podman create --entrypoint /bin/sh && podman commit — the latter corrupts Entrypoint and breaks bootc install"
Convention not obvious from code"skopeo copy must run inside the installer container, not the build host — otherwise tar-split metadata format mismatches"
Trial-and-error discovery"dmsquash-live requires CDLABEL=DAKOTA_LIVE exactly — changing the label breaks live boot without any helpful error message"
CI/environment quirk"BTRFS hosts: even with squash-to-1-layer, VFS import is slow — use XFS loopback for local builds"
Project-internal fact correction"The dakota image tag is :latest from ghcr.io/projectbluefin/dakota — verify via payload_ref file, not from memory."

Project-internal fact drift is a first-class failure mode. When an agent writes documentation about image names, tags, workflow outputs, registry paths, R2 bucket layout, or any other project-internal fact — and gets it wrong because it used training data instead of reading the source — that is a skill failure. The fix is always the same: read the source file (payload_ref, execute-release.yml, build-iso.yml), update the skill, add verification commands so the next agent can self-check.

The rule: Any skill file containing project-internal facts (image names, tag schemas, R2 paths, workflow matrix values) must include the exact source to re-derive those facts (e.g., cat <variant>/payload_ref or gh workflow view build-iso.yml).

Do NOT write:

CategoryExample
One-off task note"Use commit message fix(iso): revert squash logic for this PR"
Obvious developer knowledge"Run git status to see changed files"
Ephemeral state"R2 uploads are currently paused due to credential rotation"
Contradiction of another skillIf a skill says X and you want to say not-X, update the existing skill to say not-X — don't add a new doc

Where to Write It#

Working in...Write to
ISO build system, justfile, squashfsdocs/build.md
Architecture, boot flow, VFS storagedocs/architecture.md
CI workflows, R2 uploads, smoke testsdocs/ci.md
LUKS testing, fisherman, QEMUdocs/luks-testing.md
R2 promotion, named releasesdocs/r2-promotion.md
Variants, payload_ref patterndocs/variants.md
Issue lifecycle, labels, PR policydocs/skills/label-workflow.md
Human gates, evidence requirementsdocs/skills/human-gates.md
Onboarding, dev environmentdocs/skills/onboarding.md
Skill-drift CI check behaviordocs/skills/skill-drift.md
New process or procedure (no existing file)Create docs/skills/<area>.md

If a pattern affects 2+ projectbluefin repos, write it locally first, then open a propagation issue in projectbluefin/common.


Format#

Add a dated section at the bottom of the relevant file:

### <what you learned> (YYYY-MM-DD)

**What failed:** <describe the symptom>
**Why:** <root cause>
**Fix:** <what to do instead>

```bash
# code example if applicable

Keep it concise. Future agents need to understand it at a glance.

---

## Committing

Skill file updates must be committed in the **same PR** as the change that generated the learning. Never a follow-up PR.

```bash
git add docs/build.md # or whichever file you updated
git commit --amend # add to the existing commit, or
git commit -m "docs(build): add lesson on buildah squash entrypoint bug"

See Also#

  • docs/skills/skill-drift.md — how the CI enforcement works (warns on PRs that change code without updating docs)
  • Org-level skill-improvement mandate — cross-repo version of this document
Documents
Changelogs
Bluefin LTS Errata
Pin Log
2024-12-30-ublue-2024-wrapup
2025-01-01-announcements-archive
2025-02-23-february-update
2025-05-14-bluefin-f42
2025-06-23-bazaar-default
2025-07-06-fresh-bluefin-isos-and-bazaar
2025-07-11-four-years-of-ublue
2025-07-15-bold-brew
2025-07-17-ask-projectbluefin
2025-08-01-august-wallpapers
2025-08-08-bluefin-on-lfx
2025-08-29-github-oss-fund
2025-09-17-color-with-bluefin
2025-09-18-bluefin-lts-and-gdx
2025-09-23-LTS-at-indiafoss
2025-10-28-bluefin-autumn
2025-10-31-fastfetch-metrics
2025-11-15-cloud-native-milestone-15-million
2025-11-16-coreos-desktop
2025-11-24-new-just-and-bbrew
2025-11-27-bluefin-and-paleoartists
2025-12-04-flatpak-support-in-brewfiles
2025-12-06-interview-with-michael-tunnell
2025-12-07-documentation-updates
2025-12-14-huntress-holiday-wallpapers
2025-12-15-easier-homebrew-installation-for-custom-images
2025-12-27-upcoming-homebrew-cli-changes
2025-12-30-bluefin-2025-wrapup
2026-01-03-modernizing-custom-images
2026-02-01-automated-reports-changelogs
2026-03-13-bluefin-cli-mac-wsl
2026-03-27-bluefin-lts-gnome-49-50
2026-03-29-composefs-fisherman
2026-03-29-composefs-fisherman-design
2026-03-30-boot-verification
2026-03-30-boot-verification-design
2026-03-30-proportional-progress-tracking
2026-03-30-proportional-progress-tracking-design
2026-04-02-state-of-ecosystem
2026-04-19-dakota-alpha-1
2026-05-12-bluefin-spring-2026
2026-05-13-bluefin-spring-2026-2
2026-05-14-making-our-own-fate
2026-05-15-hummingbird
2026-05-23-gradia-capture-bluefin
2026-05-28-knuckle
2026-06-11-promotion-pr-body
AGENTS
AGENTS
AGENTS
AGENTS
AGENTS
Building a Custom Bluefin Image
CI_CD_GUIDE
CLAUDE
CLAUDE
CONTRIBUTING
CONTRIBUTING
CONTRIBUTING
CONTRIBUTING
How can I install Double Commander on Bluefin (an immutable Linux OS), coming from Arch Linux?
How can you fix random GPU artifacts and hard freezes on an AMD Framework 16 laptop running Linux (Bluefin/Fedora)?
How do I install the Cloudflare WARP (One) client on Bluefin?
How to Reset a User's Home Directory to Defaults on Bluefin
INDEX
MAINTAINERS
MULTI_VARIANT_BUILD
PITFALLS
PULL_REQUEST_TEMPLATE
Plex Media Server
README
README
README
README
README
README
README
README
SECURITY
SECURITY
SKILL
SKILL
SKILL
SKILL
TRANSLATING
Update Process
Which Bluefin ISO is recommended for a Lenovo Yoga Pro 9i with an NVIDIA RTX 4050 for Python data science and Machine Learning with CUDA?
action-reference
actionadon
add-package
administration
agentic-contributing
ai
analytics
architect
architecture
artwork
blog-poster.agent
bluefin-dx
bonedigger-overview
bonedigger-templates
bonedigger-ujust
bst-overrides
build
build
buildstream
ci
ci
ci
code-of-conduct
command-line
composite-actions
consumer-guide
consumer-validation
contributing
conventional-commit.prompt
copilot-instructions
copilot-instructions
copilot-instructions
copilot-instructions
dakota-tpm2-validation
debugging
demo-mode-e2e
determinism
dinosaurs
downloads
downloads-testing
driver-versions
e2e-ci
e2e-feature-verification
encryption-matrix
factory-operations
failure-paths
feedback-loop
gstreamer-codec-validation
human-gates
images
index
index
installation
installer
label-workflow
libpastry-integration
live-iso
local-ota
luks-testing
merge-queue
mission
multi-arch
music
not-bluefin
oci-assembly
oci-layers
onboarding
overview
packaging-binaries
packaging-gnome-extensions
packaging-go
packaging-rust
packaging-zig
patch-junctions
patches
pr-checklist
pr-review
press-kit
projects
pull_request_template
pull_request_template
pull_request_template
qr-phone-companion
quickstart
r2-promotion
release-qualification
remove-package
reports
reusable-workflow
skill-improvement
supply-chain
t2-mac
testing
troubleshooting
ujust-recipes
update-refs
upgrade-and-migration
ux-ubuntu-provision
values
variants
vm-stack
workflow