176 lines
8.9 KiB
Markdown
176 lines
8.9 KiB
Markdown
---
|
|
status: resolved
|
|
parent: "[[031-slice-skill-map]]"
|
|
claimed-by: "019fbb2a-dbcd-79d2-ae72-c5bcdd1d714e"
|
|
claimed-at: "2026-07-31T23:19:15-04:00"
|
|
blocked-by:
|
|
- "[[032-slice-skill-old-to-tasks-research]]"
|
|
- "[[036-slice-skill-matt-to-tickets-research]]"
|
|
- "[[037-slice-skill-wayfinder-contract-research]]"
|
|
tags:
|
|
- ticket/task/afk
|
|
---
|
|
|
|
# Slice skill implementation spec
|
|
|
|
## Question
|
|
|
|
Produce an implementation-ready specification for the `slice` skill.
|
|
|
|
## What to build
|
|
|
|
Write the skill specification that a later implementation step can translate directly into `skills/slice/SKILL.md` and any support files.
|
|
The spec should define invocation inputs, source-material handling, Wayfinder parent resolution, task-ticket artifact creation, blocking-edge rules, AFK versus human task classification, user review before writes, and verification expectations.
|
|
|
|
## Specification
|
|
|
|
### Purpose
|
|
|
|
`slice` turns settled source material into implementation-ready Wayfinder task tickets.
|
|
The source material may be a plan, spec, current conversation, issue text, existing artifact, or other explicit reference supplied by the caller.
|
|
The output is a set of open, unclaimed Wayfinder `ticket/task/afk` and `ticket/task/human` artifacts that represent tracer-bullet implementation slices.
|
|
|
|
### Invocation boundary
|
|
|
|
`slice` is explicitly invoked.
|
|
It should not be implicitly selected by the model because it writes multiple durable handoff artifacts and shapes future implementation work.
|
|
The caller's invocation is sufficient permission to slice the provided source material.
|
|
The skill does not require the source map to be complete, and it does not second-guess the user's decision to slice.
|
|
If the source material clearly contains unresolved planning questions rather than settled implementation input, `slice` should surface that as a problem in the proposed breakdown rather than inventing implementation work.
|
|
|
|
### Source handling
|
|
|
|
The skill works from conversation context first.
|
|
If the caller passes paths, artifact links, issue references, or URLs, the agent reads the referenced body and relevant comments or surrounding artifact context before slicing.
|
|
When source material names a Wayfinder artifact, that artifact should be the default provenance parent.
|
|
When no source artifact exists, use the active map if one is clear from context.
|
|
When neither exists, create or select the minimal Wayfinder parent required by the artifact contract rather than writing orphaned task tickets.
|
|
|
|
The agent may explore the codebase when the current implementation state is not already understood.
|
|
Titles and descriptions should use the project's established vocabulary and respect relevant ADRs or context artifacts.
|
|
The agent should look for prefactoring that makes the change easier before slicing implementation behavior.
|
|
|
|
### Artifact destination and naming
|
|
|
|
Resolve the artifact destination before naming files.
|
|
Use an explicitly supplied destination directory exactly.
|
|
Otherwise use Wayfinder's default destination resolution.
|
|
Read the destination's `AGENTS.md` before any artifact write.
|
|
Follow the destination's naming, identifier allocation, slug, and wikilink conventions.
|
|
|
|
For the AI-artifacts vault, project artifacts are flat files named `<NNN>-<scope-slug>[-<subject-slug>]-<artifact-type>.md`.
|
|
Task slice artifacts use the `task` artifact-type suffix because Wayfinder forbids `ticket` as a ticket filename suffix.
|
|
Allocate identifiers by incrementing the vault root `.counter` before artifact creation when the destination convention requires identifiers.
|
|
Preserve identifiers and update wikilinks if any file is renamed.
|
|
|
|
### Slicing discipline
|
|
|
|
Each normal slice is a tracer bullet.
|
|
It must deliver a narrow complete path through every layer the change requires, not a horizontal layer-only chunk.
|
|
A completed slice must be demoable or verifiable on its own.
|
|
A slice should make sense as one coherent commit.
|
|
Prefactoring that makes the implementation easy should appear before dependent behavior slices.
|
|
|
|
Wide mechanical refactors are the exception to strict vertical slicing.
|
|
When one mechanical change has a blast radius that prevents any vertical slice from landing green, use expand-contract sequencing instead of forcing artificial vertical slices.
|
|
Create an expand task that adds the new form beside the old one, migration batch tasks sized by blast radius, and a contract task blocked by all migrations.
|
|
If migration batches cannot stay green alone, preserve the sequence but identify the integration-branch constraint and add a final integrate-and-verify task.
|
|
|
|
### Blocking edges and Frontier
|
|
|
|
Every slice declares its blockers.
|
|
Use Wayfinder `blocked-by` wikilinks, not filename stems, issue IDs, or prose-only references.
|
|
Use `parent` only for provenance.
|
|
Use `blocked-by` for prerequisites that must resolve before the slice is actionable.
|
|
A slice with no blockers can be worked immediately.
|
|
After writing task artifacts, re-read the map and recompute its Frontier from ticket metadata.
|
|
Open, unclaimed, unblocked task tickets belong on the Frontier.
|
|
|
|
### AFK versus human tasks
|
|
|
|
Use `ticket/task/afk` when an agent can complete and verify the slice without live human input.
|
|
Use `ticket/task/human` when execution or validation depends on the user, such as subjective UI judgment, physical device checks, credentials the agent cannot access, or behavior only the human can confirm.
|
|
Do not mark a task human merely because it is important.
|
|
Make the required human involvement precise in the task body.
|
|
|
|
### Task artifact shape
|
|
|
|
Each created slice task starts with Wayfinder frontmatter:
|
|
|
|
```markdown
|
|
---
|
|
status: open
|
|
parent: "[[<source-artifact-or-map>]]"
|
|
blocked-by: []
|
|
tags:
|
|
- ticket/task/afk
|
|
---
|
|
```
|
|
|
|
Use `ticket/task/human` for human-dependent slices.
|
|
The body contains:
|
|
|
|
```markdown
|
|
# <task name>
|
|
|
|
## Question
|
|
|
|
<one precise implementation action sized to one agent session>
|
|
|
|
## What to build
|
|
|
|
<concise end-to-end behavior or implementation result, not a layer-by-layer checklist>
|
|
|
|
## Acceptance criteria
|
|
|
|
- [ ] <observable criterion>
|
|
|
|
## Implementation Notes
|
|
|
|
<concise handoff guidance when useful>
|
|
```
|
|
|
|
`## Implementation Notes` may be empty when no guidance is useful.
|
|
Later implementing agents may append execution notes, verification results, and reasons for deliberately dropped criteria.
|
|
Avoid brittle file paths and code snippets unless a prototype or prior decision snippet encodes the decision more precisely than prose can.
|
|
|
|
### Review loop
|
|
|
|
Before writing artifacts, present the proposed breakdown and wait for approval unless the caller explicitly asks for noninteractive output.
|
|
For each proposed slice show the title, task type, blockers, what it delivers, and relevant user stories or source requirements.
|
|
Ask the user to validate granularity, blocking edges, and whether any slices should be merged or split.
|
|
Iterate until the breakdown is approved.
|
|
|
|
In explicitly noninteractive mode, write the best breakdown and record any assumptions in `## Implementation Notes`.
|
|
|
|
### Relationship to other Wayfinder tickets
|
|
|
|
`slice` creates implementation task tickets.
|
|
It does not create research, prototype, or grill tickets as part of normal slicing.
|
|
If slicing reveals a precise unresolved planning question, report it and either stop or create the appropriate Wayfinder ticket only when the caller asks for that planning work.
|
|
Implementation detail belongs in task artifacts, not in the map's Decisions so far.
|
|
The map records only concise route decisions and keeps the Frontier as its only ticket-link section.
|
|
|
|
### Verification expectations
|
|
|
|
The implemented skill should be packaged as `skills/slice/SKILL.md` in this repository.
|
|
It should not write `.claude/tasks/` as an output target.
|
|
It may mention the legacy format only to say it is intentionally replaced.
|
|
Repository verification should include `nix flake check "path:$PWD"` while the new skill files are untracked.
|
|
|
|
## Acceptance criteria
|
|
|
|
- [x] The spec states that `slice` creates Wayfinder `ticket/task/afk` and `ticket/task/human` artifacts rather than legacy `.claude/tasks/` files.
|
|
- [x] The spec explains how `slice` resolves the artifact destination and chooses the parent artifact or map according to Wayfinder artifact rules.
|
|
- [x] The spec preserves tracer-bullet vertical slicing and the wide-refactor expand-contract exception.
|
|
- [x] The spec defines task body sections for `## What to build`, `## Acceptance criteria`, and `## Implementation Notes`.
|
|
- [x] The spec requires a review loop before writing artifacts unless the caller explicitly asks for noninteractive output.
|
|
- [x] The spec distinguishes implementation task tickets from Wayfinder research, prototype, and grill decision tickets.
|
|
|
|
## Implementation Notes
|
|
|
|
The specification uses the old `to-tasks`, Matt `to-tickets`, and Wayfinder contract research as its evidence base.
|
|
Sizing is specified around coherent single commits rather than fresh context windows.
|
|
The wide-refactor exception is framed as an exception to strict vertical slicing.
|
|
Keep the implementation focused on skill behavior rather than adding repository-specific execution helpers.
|