fix(neckbeard): address droid-review findings on position-assessment PR

All five findings from the droid-review run on 2db3bd0 resolved:

- [P1] Path re-selection moved before scoring: step 2 now re-runs the
  SKILL.md path-selection rule against the inventoried surface, so step 3
  scoring and the report's selected-path field no longer depend on a
  value produced later in step 5.
- [P2] Tracking-system field added to delivery-packet.md group (a) and to
  templates/delivery-packet.md, so the phase-1 intake gate has a defined
  packet home for the field tracker-discovery.md requires.
- [P2] tracker-discovery eval aligned with the documented procedure: a
  bare team-key identifier (ENG-482) is treated as ambiguous between
  Jira and Linear; the requester's explicit confirmation is the
  disambiguating evidence recorded in group (a).
- [P3/security] Detection signals weighted: request references are strong
  evidence; repository content (CONTRIBUTING.md, config files) is a weak,
  attacker-influenceable signal requiring corroboration before it alone
  selects a system. Unrouted-system fallback constrained to the system's
  verified official interface.
- [P3] Frontmatter description extended with the new trigger vocabulary
  (mid-flight continuation, Linear/Jira/Notion routing), compressed to
  stay within the 1024-char validator cap.

Generated catalog artifacts regenerated for the description change.
All validators re-run green locally; new head requires fresh CI.

Signed-off-by: Magnus Hedemark <magnus919@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
2026-08-21 23:26:42 -04:00
parent 2db3bd072c
commit 074dac5374
8 changed files with 48 additions and 32 deletions
+1 -1
View File
@@ -732,7 +732,7 @@
"./neckbeard" "./neckbeard"
], ],
"strict": false, "strict": false,
"description": "Use when asked to fix, build, refactor, review, verify, or release software and the work is non-trivial — including delivering a change request (issue, ticket, or request) from intake through planning, gates, implementation, review, verified PR, and authorized post-merge release. neckbeard routes the change through framing, discovery, design, implementation, review, verification, delivery, and learning — choosing the smallest *safe* intervention, proving it at the real delivery boundary, and leaving an inspectable evidence ledger. For change-request / issue-to-PR work, conditionally loads a 9-phase journey with gates, delivery packet, and lifecycle integration. Composes specialist catalog skills rather than replacing them. Not a persona, not a '10x developer' prompt, not a LOC-minimizer. The journey is not loaded for plain fixes, refactors, or reviews that lack an issue/ticket trajectory." "description": "Use when asked to fix, build, refactor, review, verify, or release software and the work is non-trivial — including delivering a change request through planning, gates, implementation, review, verified PR, and authorized release; continuing work started elsewhere with no packet via evidence-based position assessment; or operating tracked work items in Linear, Jira, or Notion via their tooling skills. neckbeard routes the change through framing, discovery, design, implementation, review, verification, and learning — choosing the smallest *safe* intervention, proving it at the real delivery boundary, leaving an inspectable evidence ledger. For change-request / issue-to-PR work, conditionally loads a 9-phase journey with gates, delivery packet, and lifecycle integration. Composes specialist catalog skills rather than replacing them. Not a persona, not a '10x developer' prompt, not a LOC-minimizer. The journey is not loaded for plain fixes, refactors, or reviews that lack an issue/ticket trajectory."
}, },
{ {
"name": "notion", "name": "notion",
+1 -1
View File
@@ -82,7 +82,7 @@
- [ml-engineering](ml-engineering/SKILL.md): Plan and execute production ML engineering work — model training and fine-tuning (LoRA/QLoRA), evaluation and eval-set design, quantization decisions, inference deployment, and regression triage, grounded in practical engineering patterns for production ML systems. Do not use for statistical modeling and experimental design (that's the data scientist) or for operating a specific inference engine (that's a tool skill such as llama-cpp or vllm). - [ml-engineering](ml-engineering/SKILL.md): Plan and execute production ML engineering work — model training and fine-tuning (LoRA/QLoRA), evaluation and eval-set design, quantization decisions, inference deployment, and regression triage, grounded in practical engineering patterns for production ML systems. Do not use for statistical modeling and experimental design (that's the data scientist) or for operating a specific inference engine (that's a tool skill such as llama-cpp or vllm).
- [mobile-development](mobile-development/SKILL.md): Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission (App Store and Play Store), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Use when the task involves creating, building, testing, or shipping a mobile app for iOS or Android, or reasoning about mobile behavior such as background execution, push notifications, offline storage, and data sync. Do not use for web frontend work (that is frontend-engineering), backend services and APIs (that is backend-engineering), or desktop and web platform targets outside the iOS and Android scope. - [mobile-development](mobile-development/SKILL.md): Build, test, sign, and ship mobile apps across iOS, Android, Flutter, and React Native — project scaffolding, builds and code signing, device and emulator testing, store submission (App Store and Play Store), app lifecycle and backgrounding, offline and sync, and mobile-specific testing. Use when the task involves creating, building, testing, or shipping a mobile app for iOS or Android, or reasoning about mobile behavior such as background execution, push notifications, offline storage, and data sync. Do not use for web frontend work (that is frontend-engineering), backend services and APIs (that is backend-engineering), or desktop and web platform targets outside the iOS and Android scope.
- [multi-tenant-saas-architecture](multi-tenant-saas-architecture/SKILL.md): Design and review end-to-end multi-tenant SaaS architectures: tenant and subscription semantics, control and application planes, pooled or isolated tenancy, onboarding, entitlements, metering, billing handoffs, lifecycle, partitioning, and tenant-aware operations. Use when a subscription product needs a coherent tenant model and architecture decision across these seams. Do not use for threat modeling or isolation controls, API contract semantics, data-platform design, backend implementation, migration execution, privacy compliance artifacts, capacity evidence, financial modeling, or infrastructure operations; route those to the named specialist owners. - [multi-tenant-saas-architecture](multi-tenant-saas-architecture/SKILL.md): Design and review end-to-end multi-tenant SaaS architectures: tenant and subscription semantics, control and application planes, pooled or isolated tenancy, onboarding, entitlements, metering, billing handoffs, lifecycle, partitioning, and tenant-aware operations. Use when a subscription product needs a coherent tenant model and architecture decision across these seams. Do not use for threat modeling or isolation controls, API contract semantics, data-platform design, backend implementation, migration execution, privacy compliance artifacts, capacity evidence, financial modeling, or infrastructure operations; route those to the named specialist owners.
- [neckbeard](neckbeard/SKILL.md): Use when asked to fix, build, refactor, review, verify, or release software and the work is non-trivial — including delivering a change request (issue, ticket, or request) from intake through planning, gates, implementation, review, verified PR, and authorized post-merge release. neckbeard routes the change through framing, discovery, design, implementation, review, verification, delivery, and learning — choosing the smallest *safe* intervention, proving it at the real delivery boundary, and leaving an inspectable evidence ledger. For change-request / issue-to-PR work, conditionally loads a 9-phase journey with gates, delivery packet, and lifecycle integration. Composes specialist catalog skills rather than replacing them. Not a persona, not a '10x developer' prompt, not a LOC-minimizer. The journey is not loaded for plain fixes, refactors, or reviews that lack an issue/ticket trajectory. - [neckbeard](neckbeard/SKILL.md): Use when asked to fix, build, refactor, review, verify, or release software and the work is non-trivial — including delivering a change request through planning, gates, implementation, review, verified PR, and authorized release; continuing work started elsewhere with no packet via evidence-based position assessment; or operating tracked work items in Linear, Jira, or Notion via their tooling skills. neckbeard routes the change through framing, discovery, design, implementation, review, verification, and learning — choosing the smallest *safe* intervention, proving it at the real delivery boundary, leaving an inspectable evidence ledger. For change-request / issue-to-PR work, conditionally loads a 9-phase journey with gates, delivery packet, and lifecycle integration. Composes specialist catalog skills rather than replacing them. Not a persona, not a '10x developer' prompt, not a LOC-minimizer. The journey is not loaded for plain fixes, refactors, or reviews that lack an issue/ticket trajectory.
- [notion](notion/SKILL.md): Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and gates every create or update behind a --dry-run/--yes confirmation. Use when an agent needs to read Notion content, answer questions from a team wiki or database, or make a confirmed edit. Do not use for building Notion integrations or block-level page composition beyond property updates (that is Notion API application development), or for other knowledge bases (that is their own tooling). - [notion](notion/SKILL.md): Operate Notion from a terminal or agent: retrieve pages, query databases, search pages and databases, and update page properties — with a bundled notion-cli script that is read-only by default and gates every create or update behind a --dry-run/--yes confirmation. Use when an agent needs to read Notion content, answer questions from a team wiki or database, or make a confirmed edit. Do not use for building Notion integrations or block-level page composition beyond property updates (that is Notion API application development), or for other knowledge bases (that is their own tooling).
- [nous-branding](nous-branding/SKILL.md): Generate images and content consistent with the Nous Research brand identity. Use when creating visuals in the Nous / Theia / Hermes ecosystem: a "cyber-classical" style blending neo-classical statuary, cyberpunk/industrial grunge, and retro anime illustration. Covers official brand color palette, typography (Inter/IBM Plex Sans, JetBrains Mono, heavy distressed display faces), the Nous Girl mascot, texture system, and image prompt construction. Ships reference images for palette, mascot, and brand collage that can be used as img2img inputs. - [nous-branding](nous-branding/SKILL.md): Generate images and content consistent with the Nous Research brand identity. Use when creating visuals in the Nous / Theia / Hermes ecosystem: a "cyber-classical" style blending neo-classical statuary, cyberpunk/industrial grunge, and retro anime illustration. Covers official brand color palette, typography (Inter/IBM Plex Sans, JetBrains Mono, heavy distressed display faces), the Nous Girl mascot, texture system, and image prompt construction. Ships reference images for palette, mascot, and brand collage that can be used as img2img inputs.
- [open-knowledge-format](open-knowledge-format/SKILL.md): Google's Open Knowledge Format (OKF) v0.1 — an open, vendor-neutral spec for representing knowledge as markdown files with YAML frontmatter, designed for AI agent consumption. Use when the user mentions OKF, Open Knowledge Format, Google's knowledge format, LLM wiki bundles, agent knowledge packs, creating OKF bundles, validating OKF documents, or converting knowledge into the OKF standard. - [open-knowledge-format](open-knowledge-format/SKILL.md): Google's Open Knowledge Format (OKF) v0.1 — an open, vendor-neutral spec for representing knowledge as markdown files with YAML frontmatter, designed for AI agent consumption. Use when the user mentions OKF, Open Knowledge Format, Google's knowledge format, LLM wiki bundles, agent knowledge packs, creating OKF bundles, validating OKF documents, or converting knowledge into the OKF standard.
+12 -13
View File
@@ -1,18 +1,17 @@
--- ---
name: neckbeard name: neckbeard
description: >- description: >-
Use when asked to fix, build, refactor, review, verify, or release software and Use when asked to fix, build, refactor, review, verify, or release software and the work is
the work is non-trivial — including delivering a change request (issue, ticket, non-trivial — including delivering a change request through planning, gates, implementation,
or request) from intake through planning, gates, implementation, review, review, verified PR, and authorized release; continuing work started elsewhere with no packet
verified PR, and authorized post-merge release. neckbeard routes the change via evidence-based position assessment; or operating tracked work items in Linear, Jira, or
through framing, discovery, design, implementation, review, verification, Notion via their tooling skills. neckbeard routes the change through framing, discovery,
delivery, and learning — choosing the smallest *safe* intervention, proving it design, implementation, review, verification, and learning — choosing the smallest *safe*
at the real delivery boundary, and leaving an inspectable evidence ledger. For intervention, proving it at the real delivery boundary, leaving an inspectable evidence ledger.
change-request / issue-to-PR work, conditionally loads a 9-phase journey with For change-request / issue-to-PR work, conditionally loads a 9-phase journey with gates,
gates, delivery packet, and lifecycle integration. Composes specialist catalog delivery packet, and lifecycle integration. Composes specialist catalog skills rather than
skills rather than replacing them. Not a persona, not a '10x developer' prompt, replacing them. Not a persona, not a '10x developer' prompt, not a LOC-minimizer. The journey
not a LOC-minimizer. The journey is not loaded for plain fixes, refactors, or is not loaded for plain fixes, refactors, or reviews that lack an issue/ticket trajectory.
reviews that lack an issue/ticket trajectory.
license: MIT license: MIT
compatibility: Agent harness with file read/write, terminal, and skill loading. No network or runtime dependency required by the bundle itself. compatibility: Agent harness with file read/write, terminal, and skill loading. No network or runtime dependency required by the bundle itself.
metadata: metadata:
@@ -235,4 +234,4 @@ metadata, never as a success proxy.
| [references/tracker-discovery.md](references/tracker-discovery.md) | **Change-request intake** — detecting which tracking system holds the work item and routing tracker operations to the matching catalog tooling skill; keeps the journey vocabulary tracker-neutral. | | [references/tracker-discovery.md](references/tracker-discovery.md) | **Change-request intake** — detecting which tracking system holds the work item and routing tracker operations to the matching catalog tooling skill; keeps the journey vocabulary tracker-neutral. |
| [references/evaluation.md](references/evaluation.md) | Designing, running, or reporting an evaluation | | [references/evaluation.md](references/evaluation.md) | Designing, running, or reporting an evaluation |
| [templates/](templates/) | Change contract, decision record, evidence ledger, verification plan, eval report; plus [templates/delivery-packet.md](templates/delivery-packet.md) — the fillable packet, **for change-request work only** (not for a simple fix/refactor/review without an issue trajectory) | | [templates/](templates/) | Change contract, decision record, evidence ledger, verification plan, eval report; plus [templates/delivery-packet.md](templates/delivery-packet.md) — the fillable packet, **for change-request work only** (not for a simple fix/refactor/review without an issue trajectory) |
| [eval/](eval/) | Task schema, rubric, baseline protocol, fixtures, runner | | [eval/](eval/) | Task schema, rubric, baseline protocol, fixtures, runner |
File diff suppressed because one or more lines are too long
+1 -1
View File
@@ -29,7 +29,7 @@ into another or left to implication.
| Group | Name | Fields | | Group | Name | Fields |
|---|---|---| |---|---|---|
| **(a)** | **Change-request provenance** | Change-request URL or number; source type (issue / ticket / email / verbal); repository; base ref; issue/comment snapshot (request text, comments, and linked work captured at intake); head SHA at intake. | | **(a)** | **Change-request provenance** | Change-request URL or number; source type (issue / ticket / email / verbal); repository; base ref; issue/comment snapshot (request text, comments, and linked work captured at intake); tracking system identified at intake per [tracker-discovery.md](tracker-discovery.md), with its evidence basis (repository-detected or requester-confirmed); head SHA at intake. |
| **(b)** | **Granted authority + workflow mode/path** | Authority class granted (Explore / Modify / Publish / Deploy / Merge — see [risk-authority-gates.md](risk-authority-gates.md)); selected workflow mode (GitHub reference mode or enterprise mode); selected path (lightweight / full / refactor / high-risk). | | **(b)** | **Granted authority + workflow mode/path** | Authority class granted (Explore / Modify / Publish / Deploy / Merge — see [risk-authority-gates.md](risk-authority-gates.md)); selected workflow mode (GitHub reference mode or enterprise mode); selected path (lightweight / full / refactor / high-risk). |
| **(c)** | **Resumable phase/gate state + current head SHA** | Current phase name; current gate name; the head SHA at which the last successful gate verdict was recorded; the current lifecycle state (see below). | | **(c)** | **Resumable phase/gate state + current head SHA** | Current phase name; current gate name; the head SHA at which the last successful gate verdict was recorded; the current lifecycle state (see below). |
| **(d)** | **Problem / baseline evidence / scope / non-goals / affected surfaces** | User-visible problem; baseline (pre-change) evidence with boundary labels; in-scope work; explicit non-goals; affected surfaces (paths, contracts, boundaries). | | **(d)** | **Problem / baseline evidence / scope / non-goals / affected surfaces** | User-visible problem; baseline (pre-change) evidence with boundary labels; in-scope work; explicit non-goals; affected surfaces (paths, contracts, boundaries). |
+11 -6
View File
@@ -72,6 +72,11 @@ Inventory reads are read-only discovery; they need no confirmation. Record
where each artifact was found (path, SHA, URL) — pointers become the evidence where each artifact was found (path, SHA, URL) — pointers become the evidence
references in the report. references in the report.
**Re-select the delivery path here, before scoring.** Run the path-selection
rule ([../SKILL.md](../SKILL.md) § Path selection) against the affected surface
and risk observed in the inventory; do not inherit a path assumption from the
prior work. The selected path determines which phases are mandatory to score.
### Step 3 — Score against phase exit conditions ### Step 3 — Score against phase exit conditions
Compare each inventoried artifact with the exit condition and gate definition Compare each inventoried artifact with the exit condition and gate definition
@@ -87,9 +92,9 @@ of its phase ([journey.md](journey.md); gate semantics in
Scoring constraints: Scoring constraints:
- Score the selected delivery path's mandatory phases; conditional phases are - Score the delivery path selected in step 2; conditional phases are scored
scored only if their artifacts exist (an absent conditional phase with a only if their artifacts exist (an absent conditional phase with a legitimate
legitimate skip reason is recorded as such, not penalized). skip reason is recorded as such, not penalized).
- Verified-complete work is **not** re-executed, mirroring packet-resume - Verified-complete work is **not** re-executed, mirroring packet-resume
semantics. Assessment establishes position; it does not redo accepted work. semantics. Assessment establishes position; it does not redo accepted work.
- Never upgrade a verdict to fill a gap. A missing gate verdict is `absent`, - Never upgrade a verdict to fill a gap. A missing gate verdict is `absent`,
@@ -124,9 +129,9 @@ Create a fresh delivery packet so subsequent operation has normal resumability:
- Group (a) provenance records: engaged mid-flight, artifacts assessed, with - Group (a) provenance records: engaged mid-flight, artifacts assessed, with
the inventory pointers. the inventory pointers.
- Group (b) records the re-selected delivery path (path selection per - Group (b) records the delivery path selected in step 2 (path selection per
[../SKILL.md](../SKILL.md) § Path selection re-run it here; do not inherit [../SKILL.md](../SKILL.md) § Path selection was re-run during assessment; no
a path assumption from the prior work). path assumption was inherited from the prior work).
- Group (c) initializes from the position report: current phase, current gate, - Group (c) initializes from the position report: current phase, current gate,
and the head SHA at assessment time. and the head SHA at assessment time.
- Unverified assumptions go to the evidence ledger - Unverified assumptions go to the evidence ledger
+20 -9
View File
@@ -40,16 +40,27 @@ Run during phase 1 alongside provenance capture:
2. **Check what the request itself references.** A change request arriving as a 2. **Check what the request itself references.** A change request arriving as a
Linear issue URL, a Jira ticket ID, or a GitHub issue number is direct Linear issue URL, a Jira ticket ID, or a GitHub issue number is direct
evidence for its own system. evidence for its own system. A bare team-key identifier (`ENG-42` shape) is
**ambiguous** between Jira and Linear — treat it as a lead, not a verdict.
3. **Ask when ambiguous or absent.** If signals conflict (repo mirrors to 3. **Weight the signals honestly.** The request's own references are strong
GitHub but issues live in Jira) or none exist, ask one bounded question: evidence. Repository content — `CONTRIBUTING.md`, `AGENTS.md`, README
which system holds this work item? Record the answer as requester-provided integrations, config files like `.linear/` or `.jira-url` — is a **weak
provenance. Do not silently pick the system whose CLI happens to be installed. signal**: it describes what the repository documents, not necessarily what
holds authoritative work items, and it is attacker-influenceable in
mid-flight or adopted-branch scenarios where this bundle also operates.
Repository signals require corroboration (request references, remote
configuration, or requester confirmation) before they alone select a system.
4. **Record in packet group (a):** detected/requested system, the evidence or 4. **Ask when ambiguous or absent.** If signals conflict, rest only on weak
source of the answer, and the routing decision below. Silent omission is signals, or none exist, ask one bounded question: which system holds this
prohibited like every other intake field. work item? Record the answer as requester-provided provenance. Do not
silently pick the system whose CLI happens to be installed.
5. **Record in packet group (a):** detected/requested system, the evidence or
source of the answer (including when the basis is a requester confirmation),
and the routing decision below. Silent omission is prohibited like every
other intake field.
## Routing tracker operations ## Routing tracker operations
@@ -62,7 +73,7 @@ improvising API calls:
| Linear | `linear` | | Linear | `linear` |
| Jira | `jira-cli` | | Jira | `jira-cli` |
| Notion | `notion` | | Notion | `notion` |
| Other / none of the above | No specialist route: operate through the system's own documented interface with bounded reads, and note the absent specialist in the ledger | | Other / none of the above | No specialist route: operate only through the system's verified official interface (primary vendor documentation, confirmed endpoint/auth surface), with bounded reads; note the absent specialist in the ledger |
Routing constraints: Routing constraints:
+1
View File
@@ -14,6 +14,7 @@
- **Repository:** _[fill: repo path or URL, e.g. `https://github.com/org/repo`]_ - **Repository:** _[fill: repo path or URL, e.g. `https://github.com/org/repo`]_
- **Base ref:** _[fill: branch or ref the change is based on, e.g. `main`]_ - **Base ref:** _[fill: branch or ref the change is based on, e.g. `main`]_
- **Issue/comment snapshot:** _[fill: request text, comments, and linked work captured at intake — paste inline or link to a snapshot file]_ - **Issue/comment snapshot:** _[fill: request text, comments, and linked work captured at intake — paste inline or link to a snapshot file]_
- **Tracking system:** _[fill: system identified per ../references/tracker-discovery.md, e.g. `Linear (requester-confirmed)` / `GitHub Issues (detected: issue URL in request)`]_
- **Head SHA at intake:** _[fill: `git rev-parse HEAD` at intake, e.g. `a1b2c3d`]_ - **Head SHA at intake:** _[fill: `git rev-parse HEAD` at intake, e.g. `a1b2c3d`]_
## (b) Granted authority + workflow mode/path ## (b) Granted authority + workflow mode/path