SKaiNET-developers · michalharakal · Aug 31, 2026 · Aug 31, 2026
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Contributor getting started (DARC, SKEEP, lanes, labels)
+    url: https://skainet-developers.github.io/SKaiNET/skainet/contributing/getting-started.html
+    about: Read this first if you want to pick up a task — it explains the two workflows and how issues are labelled.
+  - name: Issue taxonomy
+    url: https://skainet-developers.github.io/SKaiNET/skainet/contributing/issue-taxonomy.html
+    about: What every label, title prefix and template means, and how to decompose a feature into lanes.
diff --git a/.github/ISSUE_TEMPLATE/darc_lane_task.md b/.github/ISSUE_TEMPLATE/darc_lane_task.md
@@ -0,0 +1,43 @@
+---
+name: "DARC Lane Task (sub-issue)"
+about: "One independently claimable task split out of a DARC feature — a single lane, a single skill, an honest size"
+title: "[Lane N · skill] Feature — what this task produces"
+labels: sub-issue
+assignees: ""
+---
+
+<!--
+One lane of a DARC feature. Open it as a sub-issue of the parent DARC issue
+(GitHub "Create sub-issue", or `gh issue create --parent <number>`), then add
+ONE `skill:*` label, ONE `size:*` label, the DARC phase label
+(assessment / research / coding / documentation), and `good first issue`
+if no prior SKaiNET codebase knowledge is needed.
+
+Lanes (see docs → Contributing → Issue taxonomy):
+  0 Design (SKEEP)   1 Numerics/Research   2 Kotlin core
+  3 Platform verification   4 Ground-truth/CI   5 Docs/DARC   6 Review
+-->
+
+Sub-issue of #<parent-issue-number> (<parent feature title>).
+
+**Lane:** <N · lane name>
+**Skill needed:** <what a contributor must already know — and, just as important, what they do *not* need to know>
+**Size:** <xs / s / m / l> (<rough wall-clock estimate>)
+**Blocked by:** <#issue, or "nothing">
+
+## What to do
+
+1. <concrete step>
+2. <concrete step>
+3. <concrete step>
+
+## Acceptance
+
+- [ ] <observable outcome a reviewer can check>
+- [ ] <observable outcome a reviewer can check>
+- [ ] Result reported back on the parent issue
+
+## Notes
+
+<!-- Pointers to sibling code to copy the pattern from, reference implementations,
+     gotchas, or "if X turns out to be true, stop and open a separate issue". -->
diff --git a/.github/ISSUE_TEMPLATE/skeep_tracking.md b/.github/ISSUE_TEMPLATE/skeep_tracking.md
@@ -0,0 +1,45 @@
+---
+name: "SKEEP Proposal (tracking issue)"
+about: "Track a durable design record — a public API, DSL, storage, runtime, compiler, or compatibility decision"
+title: "[SKEEP-NNN]: "
+labels: skeep, tracking
+assignees: ""
+---
+
+<!--
+A SKEEP is SKaiNET's KEEP-style proposal track. The *proposal itself* lives in
+the docs tree (docs/modules/skeep/pages/NNN-short-title.adoc); this issue is
+the day-to-day coordination layer it links back to via its `Tracking issue:`
+header field. See CONTRIBUTING.md → "SKEEP Procedure" for the full steps.
+
+Not sure whether this needs a SKEEP or "just" DARC? See docs → Contributing →
+Getting started → "DARC or SKEEP?".
+-->
+
+**Proposal document:** `docs/modules/skeep/pages/NNN-short-title.adoc` (<link once the PR is open>)
+**Status:** Draft
+**Branch:** `feature/skeep-NNN-short-title`
+
+## Trigger
+
+<!-- Which SKEEP trigger does this change trip? (public Kotlin API · DSL syntax/semantics ·
+     tensor dtype/shape/storage/execution behaviour · compiler/graph-export/runtime
+     integration · compatibility/migration policy · docs structure for a long-lived area) -->
+
+## Summary
+
+<!-- 2-5 sentences. What changes, and why an issue/PR description is not durable enough. -->
+
+## Related DARC features
+
+<!-- DARC feature issues that are blocked on, or unblocked by, this proposal. -->
+
+## Sub-issues
+
+<!-- Spike / implementation phases, filed as sub-issues once the proposal is Accepted. -->
+
+## Status upkeep
+
+- [ ] Proposal registered in `docs/modules/skeep/nav.adoc` and the "Current Proposals" table
+- [ ] Maintainer moved status to `Accepted`
+- [ ] Implementation PR(s) linked here **and** flipped the proposal's `Status:` to `Implemented`
diff --git a/.github/labels.txt b/.github/labels.txt
@@ -0,0 +1,36 @@
+# SKaiNET issue label taxonomy — source of truth for `.github/scripts/sync-labels.sh`.
+# Format: name|hex-color|description   (lines starting with # are ignored)
+# Documented in docs/modules/ROOT/pages/contributing/issue-taxonomy.adoc.
+#
+# --- Structure: how an issue relates to other issues -------------------------
+tracking|ededed|Parent/tracking issue with sub-issues
+sub-issue|ededed|Sub-issue of a tracking issue
+darc|a2eeef|Feature driven through the DARC workflow (Document / Assess / Research / Code)
+skeep|5319e7|SKEEP proposal tracking issue (durable design record)
+#
+# --- DARC phase: which phase of the workflow the task belongs to ------------
+assessment|e99695|Assessment task (DARC: A)
+research|c2e0c6|Research and evaluation tasks (DARC: R)
+coding|006b75|Implementation task (DARC: C)
+documentation|0075ca|Improvements or additions to documentation (DARC: D)
+#
+# --- Skill: what a contributor needs to know to pick the task up -------------
+skill:numerics|1d76db|PyTorch/NumPy/math background, no Kotlin required
+skill:kotlin-core|1d76db|Kotlin implementation in commonMain
+skill:android|1d76db|Android target/build/kernel work
+skill:ios|1d76db|iOS / Kotlin-Native-Apple target work
+skill:native|1d76db|Kotlin/Native (Linux, macOS) or FFM kernel work
+skill:js|1d76db|JS / Wasm target work
+skill:docs|1d76db|AsciiDoc / technical writing
+skill:review|1d76db|DARC review; must not be the task's implementer
+skill:design|5319e7|SKEEP authorship; architectural / API-shape judgement
+#
+# --- Size: honest effort estimate ------------------------------------------
+size:xs|d4f7d4|Under 1 hour
+size:s|b6ebb6|A few hours
+size:m|f9e79f|1-2 days
+size:l|f5b7a0|3+ days; likely needs its own design discussion
+#
+# --- Entry point -----------------------------------------------------------
+good first issue|7057ff|Good for newcomers; no prior SKaiNET codebase knowledge assumed
+help wanted|008672|Extra attention is needed
diff --git a/.github/scripts/sync-labels.sh b/.github/scripts/sync-labels.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Idempotently create/update the GitHub labels declared in .github/labels.txt.
+#
+# Usage:
+#   .github/scripts/sync-labels.sh                       # against the current repo
+#   .github/scripts/sync-labels.sh -R owner/repo         # against another repo
+#   DRY_RUN=1 .github/scripts/sync-labels.sh             # print what would run
+#
+# Requires `gh` authenticated with triage (or higher) permission on the repo.
+# Existing labels are updated in place (--force); labels that are not in
+# labels.txt are left untouched — this script never deletes anything.
+set -euo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+labels_file="${LABELS_FILE:-$here/../labels.txt}"
+repo_args=("$@")
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "error: gh CLI not found" >&2
+  exit 1
+fi
+
+count=0
+while IFS='|' read -r name color description; do
+  # skip comments and blank lines
+  case "$name" in ''|\#*) continue ;; esac
+  name="${name%"${name##*[![:space:]]}"}"          # rtrim
+  color="${color//[[:space:]]/}"
+  description="${description#"${description%%[![:space:]]*}"}"  # ltrim
+  cmd=(gh label create "$name" --color "$color" --description "$description" --force "${repo_args[@]}")
+  if [[ "${DRY_RUN:-0}" == "1" ]]; then
+    printf '%q ' "${cmd[@]}"; echo
+  else
+    "${cmd[@]}"
+  fi
+  count=$((count + 1))
+done < "$labels_file"
+
+echo "synced $count labels from $labels_file"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,6 +4,47 @@ SKaiNET uses the Gitflow branching model described in
 [GITFLOW.adoc](GITFLOW.adoc). Keep ordinary fixes small, focused, and easy to
 review.
 
+## Two Processes: DARC and SKEEP
+
+Non-trivial work in SKaiNET goes through one of two processes — sometimes
+both. They answer different questions:
+
+| | DARC | SKEEP |
+|---|---|---|
+| **Question** | Is *this feature* the right thing to build, and is it built to the documented design? | What is the durable *shape of the codebase* going forward? |
+| **Unit of work** | One operator, metric, layer, format reader, kernel strategy | One architectural decision: public API, DSL syntax, storage model, runtime/compiler integration, compatibility policy |
+| **Phases / states** | Document → Assess → Research → Code (cyclical) | Draft → Accepted → Implemented (or Superseded / Rejected) |
+| **Artifact** | Feature issue (`.github/ISSUE_TEMPLATE/darc_feature_request.md`) decomposed into lane sub-issues; for operators, a doc partial + `@DarcValidated` | `docs/modules/skeep/pages/NNN-short-title.adoc` + a tracking issue (`.github/ISSUE_TEMPLATE/skeep_tracking.md`) |
+| **Sign-off** | A reviewer who is not the implementer | A maintainer, by moving the `Status:` field |
+
+**Which one?** If the change trips a SKEEP trigger (next section), write the
+SKEEP first and have the DARC feature issue link to it. If it doesn't, but a
+maintainer six months from now would want to know *why* the change is shaped
+the way it is, it's DARC. Typos, obvious one-line fixes, dependency bumps and
+test-only changes need neither.
+
+Full text: [Getting started as a contributor](https://skainet-developers.github.io/SKaiNET/skainet/contributing/getting-started.html)
+and [DARC: advanced contribution workflow](https://skainet-developers.github.io/SKaiNET/skainet/contributing/darc-workflow.html)
+(sources under `docs/modules/ROOT/pages/contributing/`).
+
+## Finding Work: Issue Taxonomy
+
+A DARC feature is one parent issue (`tracking`, `darc`) plus one native
+sub-issue per *lane* — numerics research, Kotlin core, per-platform
+verification, ground-truth/CI, docs, review. Every sub-issue carries exactly
+one `skill:*` label (`numerics`, `kotlin-core`, `android`, `ios`, `native`,
+`js`, `docs`, `review`, `design`), one `size:*` label (`xs` < 1 h, `s` a few
+hours, `m` 1–2 days, `l` 3+ days), and a DARC phase label (`documentation`,
+`assessment`, `research`, `coding`). `good first issue` means no prior
+SKaiNET codebase knowledge is assumed.
+
+Useful searches: `is:open label:"good first issue"`,
+`is:open label:skill:android label:size:xs`, `is:open label:tracking label:darc`.
+
+The label set is declared in `.github/labels.txt` and applied with
+`.github/scripts/sync-labels.sh`; the full reference is
+[Issue taxonomy](https://skainet-developers.github.io/SKaiNET/skainet/contributing/issue-taxonomy.html).
+
 ## When to Write an SKEEP
 
 SKEEP stands for SKaiNET Evolution and Enhancement Process. It is the
@@ -21,7 +62,10 @@ Write an SKEEP when a change affects:
 
 You usually do not need an SKEEP for local bug fixes, internal refactors,
 dependency bumps, test-only changes, typo fixes, or implementation details that
-do not affect user-visible behavior.
+do not affect user-visible behavior. Additive features that sit behind an
+existing interface (a new metric implementing `Metric`, a new op on an existing
+backend) are DARC features, not SKEEPs — unless building them forces one of the
+triggers above.
 
 ## SKEEP Procedure
 
@@ -38,13 +82,20 @@ do not affect user-visible behavior.
    `docs/modules/skeep/pages/index.adoc`.
 6. Start new proposals with `Status: Draft`. Use `Accepted`, `Implemented`,
    `Superseded`, or `Rejected` only when maintainers have made that decision.
-7. Include the standard sections: summary, motivation, proposed design,
+   The PR that ships the implementation must also flip the status to
+   `Implemented` — a proposal whose code has shipped but whose status still
+   says `Draft` is worse than no status field at all.
+7. Open a tracking issue from `.github/ISSUE_TEMPLATE/skeep_tracking.md`
+   (title `[SKEEP-NNN]: …`, labels `skeep`, `tracking`) and put its link in
+   the proposal's `Tracking issue:` header. The proposal is the durable
+   record; the issue is where day-to-day coordination happens.
+8. Include the standard sections: summary, motivation, proposed design,
    compatibility and migration notes, rollout plan, acceptance criteria, risks,
    open questions, and references.
-8. If the proposal depends on external language or platform features, link the
+9. If the proposal depends on external language or platform features, link the
    relevant upstream documents and call out stability or compiler-flag
    requirements.
-9. Keep implementation PRs connected to the SKEEP. The proposal explains the
+10. Keep implementation PRs connected to the SKEEP. The proposal explains the
    shape of the decision; code changes prove and ship it.
 
 SKEEP files are part of the Antora docs component. The module is registered in

diff --git a/README.md b/README.md
@@ -124,14 +124,26 @@ SKaiNET is a modular ecosystem. While this repository contains the core engine,
 
 ## Contributing and Design Proposals
 
+**First time here?** Three links are all you need:
+
+- 🚀 [Getting started as a contributor](https://skainet-developers.github.io/SKaiNET/skainet/contributing/getting-started.html) — the two workflows in one page, and how to claim a task.
+- 🟣 [Open good first issues](https://github.com/SKaiNET-developers/SKaiNET/issues?q=is%3Aopen+label%3A%22good+first+issue%22) — filter further by what you know: [`skill:android`](https://github.com/SKaiNET-developers/SKaiNET/issues?q=is%3Aopen+label%3Askill%3Aandroid), [`skill:numerics` (no Kotlin)](https://github.com/SKaiNET-developers/SKaiNET/issues?q=is%3Aopen+label%3Askill%3Anumerics), [`skill:docs`](https://github.com/SKaiNET-developers/SKaiNET/issues?q=is%3Aopen+label%3Askill%3Adocs), or by size: [`size:xs`](https://github.com/SKaiNET-developers/SKaiNET/issues?q=is%3Aopen+label%3Asize%3Axs).
+- 🏷️ [Issue taxonomy](https://skainet-developers.github.io/SKaiNET/skainet/contributing/issue-taxonomy.html) — what every label and `[Lane N · skill]` title prefix means.
+
 Small fixes can go straight through the normal contribution flow described in
 [CONTRIBUTING.md](CONTRIBUTING.md) and [GITFLOW.adoc](GITFLOW.adoc).
 
-Use a SKEEP when a change affects public APIs, DSL syntax, tensor semantics,
-compiler/runtime integration, storage behavior, compatibility policy, or other
-decisions that need a durable design record. SKEEP files live under
-`docs/modules/skeep/pages/` and use three-digit numbering, starting with
-`001`.
+Non-trivial work goes through one of two processes:
+
+- **DARC** (Document / Assess / Research / Code) for *one feature* — a new
+  operator, metric, layer, format reader, or kernel strategy. A feature is one
+  parent issue plus skill-labelled sub-issues ("lanes"). See the
+  [DARC workflow](https://skainet-developers.github.io/SKaiNET/skainet/contributing/darc-workflow.html).
+- **SKEEP** (SKaiNET Evolution and Enhancement Process) for *one architectural
+  decision* — public APIs, DSL syntax, tensor semantics, compiler/runtime
+  integration, storage behavior, compatibility policy. SKEEP files live under
+  `docs/modules/skeep/pages/` with three-digit numbering. See the
+  [SKEEP index](https://skainet-developers.github.io/SKaiNET/skainet/skeep/index.html).
 
 ---
 
@@ -329,9 +341,9 @@ See [CHANGELOG.md](CHANGELOG.md) for full release notes, including every prior r
 
 We love contributions! Whether it's a new operator, documentation, or a bug fix:
 
-1. Read our [Contribution Guide](CONTRIBUTING.md).
-2. Check the [Good First Issues](https://github.com/SKaiNET-developers/SKaiNET/labels/good%20first%20issue).
-3. Open a discussion or issue on [GitHub](https://github.com/SKaiNET-developers/SKaiNET/issues).
+1. Read [Getting started as a contributor](https://skainet-developers.github.io/SKaiNET/skainet/contributing/getting-started.html) (five minutes), then the [Contribution Guide](CONTRIBUTING.md) when you need the procedure.
+2. Pick an [open good first issue](https://github.com/SKaiNET-developers/SKaiNET/issues?q=is%3Aopen+label%3A%22good+first+issue%22) — every one names the file to copy the pattern from and the exact Gradle task to run. Comment on it to claim it.
+3. Open a discussion or issue on [GitHub](https://github.com/SKaiNET-developers/SKaiNET/issues); the issue chooser has templates for DARC features, lane tasks and SKEEP proposals.
 
 Browse the full codebase documentation on [DeepWiki](https://deepwiki.com/SKaiNET-developers/SKaiNET).
 

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -53,7 +53,10 @@
 
 .Contributing
 * xref:contributing/index.adoc[Audience and scope]
+* xref:contributing/getting-started.adoc[Getting started as a contributor]
 * xref:contributing/darc-workflow.adoc[DARC: advanced contribution workflow]
+* xref:contributing/darc-worked-example-f1score.adoc[Worked example: F1Score via DARC]
+* xref:contributing/issue-taxonomy.adoc[Issue taxonomy]
 * xref:contributing/build-from-source.adoc[Build from source]
 * xref:contributing/dtype-model.adoc[The SKaiNET dtype model]
 * xref:contributing/benchmarks.adoc[Engine benchmark program]