Feature-authoring process with scoped writer role

Family

authoring

Status

proposed

Complexity

medium

Advances

PL1-task-decomposition PL3-skill-library-health PL5-multi-agent-delegation

Prerequisites

PL1-corpus-taxonomy ≥ 2, PL1-task-decomposition ≥ 1

Feature-authoring process with scoped writer role

Purpose

Codify the Pillar-1 task-decomposition work of authoring a feature as a reusable, role-scoped process — so that going from “we should probably do X” to feature file ready to commit follows a named pattern rather than session-variable practice. The pattern separates writing about a feature (task decomposition, scoping, spec) from implementing the feature (code, config, infra) via sparse-checkout-scoped sessions, and clusters the authoring work into three invokable skills (scope, draft, review) within a single feature-writer role. Research discipline is preserved by commissioning separate research field-agents for each load-bearing technical claim.

Architecture

Four moving parts: one coordinator role, three skills within it, a set of field-agents it commissions, and a hard sparse-checkout boundary that keeps its concerns separate from implementation.

1. One role — feature-writer

A single working session scoped to Pillar-1 task-decomposition. User resumes this session whenever a new feature needs authoring; context is cleared at feature boundary with /clear. The role holds:

• Context scope — read access to the canon’s task-decomposition surface only: the rubric, all artefact indexes + entries (features/, recipes/, research/, references/, internal/integrations/, memory/stakeholders/, briefings/, conversations/), all _template.mds, CLAUDE.md, README.md. No access to implementation subtrees (code packages, infra, workflows, ops scripts) — those are the implementer role’s concern and would dilute context without informing scoping decisions.
• Tools — Read, Glob, Grep for canon exploration; Edit, Write to author feature files and scoping / review artefacts; Agent to commission research field-agents; Bash scoped to local read commands (find, wc, git status) without network access. No WebFetch / WebSearch (delegated to research field-agents), no external-comms MCPs (Slack, email), no git push / PR creation (human retains).
• Purpose boundary — produces feature artefacts (the feature file + its scoping-notes and review-notes siblings) and nothing else. Does not write code. Does not wire infrastructure. Hands off to implementation via a committed feature file.

2. Three skills within the writer

The nine phases of feature authoring cluster naturally into three invokable skills. Each skill is a named prompt the user addresses the writer session with; transitions between skills are user-gated (typically /clear + next invocation).

scope skill — phases 1-5.

1. Rubric grounding — locate the proposed feature’s concern in the existing rubric; identify one or more criterion slugs it would advance.
2. Corpus inventory — walk the artefact classes to surface existing work (features, research, recipes, integrations, references) that touches the concern.
3. Shape-of-work conversation — interview the user to surface the load-bearing axes (private vs public, local vs cloud, one vs many, naming conventions, constraints) before any commitment.
4. Primary-source research — commission research field-agents for each load-bearing technical choice. Typically serial: most features touch one or two core technologies, and later researches depend on earlier decisions. Parallel only when researches are genuinely independent.
5. Architecture decisions — surface tradeoffs from research findings; user picks; decisions land in research Decision / Ruled-out sections or in the scoping notes.

Exit criterion: a scoping brief committed at features/<slug>-scoping-notes.md containing criterion(s) advanced, inventory findings, linked research, locked architecture decisions, proposed feature name + slug, open decomposition questions.

draft skill — phase 6.

6. Feature draft — author the feature file against the canon’s feature template from the scoping brief. Follow bidirectional cross-reference discipline: related_research, related_recipes, related_integrations, depends_on frontmatter populated; opposite-direction links updated on the cited artefacts. Every criteria_advanced slug is a valid rubric criterion.

Exit criterion: internal/features/<slug>.md exists and passes template compliance; index row added to internal/features/README.md.

review skill — phases 7-9. Runs on a freshly-cleared context (minimum: /clear between draft and review; stronger: separate session on a different day) so the reviewing perspective doesn’t carry drafter bias.

7. Decomposition check — is this one feature or multiple? Load-bearing shared infrastructure that downstream features would reuse gets extracted into its own feature with a depends_on relationship. If decomposition happens, the extracted feature loops back through scope and draft.
8. Structural-enforcement walk-through — systematic audit for procedural gates that could be structural. Specific anti-patterns to check:
   • Human-checkbox gates where a workflow, script, or compiler could enforce
   • Manual settings with no drift detection
   • Prose rollback commands vs idempotent scripts
   • Prose setup documentation vs setup scripts
   • Runtime soft-fail / hard-fail state tracking vs committed-in-git thresholds
   • Reviews that could be tests
9. Human-touchpoint audit — enumerate every human action across phase-0, rollout, and ongoing operations; interrogate each for reducibility. Phase-0 should contain only irreducible trust-bootstrap actions.

Exit criterion: a gap report committed at features/<slug>-review-notes.md with ordered findings, each marked apply / skip / discuss. User chooses which gaps to fix; fixes land via re-invoking draft. Review may re-run once fixes land.

Feature is commit-ready when the review report has no outstanding apply items and the user has accepted the skip tradeoffs. The scoping-notes and review-notes files may remain committed (absorbed into the feature’s Retrospective at status: complete) or be deleted on completion — a tenant choice.

3. Research field-agents — commissioned, not bundled

The writer never fetches web content directly. Each load-bearing technical claim is delegated to a research field-agent via the Agent tool. Each research agent:

• Receives a brief containing: context (what the research is for), prior decisions (what not to relitigate), primary sources to fetch, specific questions to answer, deliverable shape (reference doc + research doc following the canon’s templates), scope discipline (don’t edit rubric, don’t commit, don’t duplicate other agents’ work).
• Fetches primary sources via WebFetch; distils each into a references/<slug>-docs.md entry with fetch-date provenance.
• Authors a research/<slug>.md entry citing the reference doc, following the research template (Decision, Findings, Ruled-out, Implications, Open questions).
• Updates internal/references/README.md and internal/research/README.md index rows, populates bidirectional cross-references on any research docs it cites as siblings.
• Returns a condensed report to the writer (ten-to-fifteen-line-each answers to the brief’s questions, plus surprises).

The writer verifies the research agent’s work: files exist, bidirectional cross-references applied, no rubric edits proposed unilaterally. Findings are validated with the user before architecture decisions are locked.

4. Sparse-checkout boundary — writer vs implementer

The hard split is not among scope, draft, review (those share context and are one session); it is between the feature-writer role and the feature-implementer role. Implementation is out of scope for this recipe and described separately in a sibling recipe (see Related recipes), but the sparse-checkout discipline the writer observes makes the boundary enforceable:

• Writer session — sparse-checkout excludes implementation directories. Cannot accidentally modify code while drafting a feature spec.
• Implementer session — sparse-checkout includes the specific implementation subtree(s) + the feature file being implemented + any adjacent research / recipes cited by that feature. Excludes the broader canon to keep PL1-codebase-scoping tight.

Lethal-trifecta partitioning across the composed roles:

Role	Private data?	Untrusted content?	External comms?	Legs held
feature-writer	Yes (canon)	No (no WebFetch)	No	1 — clean
research field-agent	Narrow (template + cited refs)	Yes (WebFetch)	No	2 — clean
feature-implementer	Yes (narrow subtree)	No	No	1 — clean

No role simultaneously holds legs 1 + 2. Research outputs cross the writer-vs-web boundary via artefact files merged to main through PR review — the same ingestion-as-PR gate the canon already uses for external content. Outbound communication (commits, pushes, PR creation, Slack alerts) remains a human action or lives in workflow YAML authored by the writer, never in the writer’s or research agent’s own tool surface.

Criteria advanced

• PL1-task-decomposition — level 2 → contributing to level 3. Mechanism: Pass-1 of the recipe ships a named, repeatable process that produces feature files matching the features/_template.md shape. Gate quality compounds — each feature’s review-notes file surfaces patterns (which anti-pattern was caught most often, which phases produced the most edits) that feed back into template and prompt refinement. Full level-3 depends on enough features passing through the loop to reveal reliable patterns; the recipe is the scaffold, not the compound signal itself.
• PL3-skill-library-health — direct contribution. Mechanism: adds three named, inventoried, documented, testable skills (scope, draft, review) plus one named role (feature-writer) to the canon’s skill library. Each skill has a defined prompt shape, entry/exit criteria, and specific anti-patterns it guards against; the role has defined tool scope, sparse-checkout, and trifecta posture. Coverage is mapped against Pillar 1’s task-decomposition surface — the library is not just bigger, it fills a specific gap.
• PL5-multi-agent-delegation — direct contribution toward level 2. Mechanism: the recipe explicitly names differentiated full-stack roles (feature-writer, research field-agent, feature-implementer) with distinct context scopes, tools, permissions, and prompts. Handoffs between roles are user-gated (between skills) or artefact-mediated (research outputs via PR, implementer handoff via committed feature file), making approval authority observable. Lethal-trifecta partitioning is structurally enforced by the sparse-checkout and tool scopes, not by convention. The feature-implementer role is out-of-scope for this recipe’s own delivery but its existence as a scoped sibling is part of the architecture.

Prerequisites

• PL1-corpus-taxonomy ≥ 2. The recipe assumes the canon already has clear artefact classes with templates and indexed registries — the writer’s scope skill walks those indexes during inventory, and the draft skill’s cross-reference discipline depends on them existing. Without this substrate, “find related research” and “add feature to index” collapse back into ad-hoc file creation.
• PL1-task-decomposition ≥ 1. A features/_template.md with non-trivial structure (frontmatter, Scope, Acceptance criteria, Task breakdown, Dogfood targets, etc.) must exist. The draft skill is a process for filling it in, not for inventing it. Canon projects at level 0-1 (no feature template, or a stub) need to author the template first — arguably a single-use application of this recipe to produce its own prerequisite, which is fine as a bootstrap but shouldn’t be mistaken for the recipe’s normal operation.
• Agent tool availability. The scope skill commissions research field-agents programmatically. Environments without a sub-agent primitive have to substitute a human research role — possible, but loses the trifecta-separation guarantee the primitive provides.

Failure modes

• Skills collapsed into one blob. Writer runs scope + draft + review in one uninterrupted session without /clear between draft and review. Loses the cold-context gap-finding benefit; reviewer-as-same-agent is a known blind-spot. Watch for: no -review-notes.md file produced, or review-notes that merely restate the feature rather than challenging it.
• Research skipped for obvious shapes. “We’ve used this tech before, no need to research” — plausible in isolation but erodes the primary-source-access discipline. Decisions made without primary-source backing can’t be cited later, and the next person doing similar work re-derives from scratch. Mitigation: research is the default; skipping requires an explicit rationale noted in the scoping brief (pointing at the existing reference/research that covers the decision).
• Parallel research when decisions depend. Research B needs Research A’s output; launched in parallel, B either produces wasted work or frames itself around a wrong assumption. Mitigation: most features touch one or two core technologies; serial is the default; parallel only when the independence has been specifically verified.
• Writer-implementer session collapsed. The writer’s Write tool gets used for implementation code, not just feature artefacts. Sparse-checkout discipline erodes; the feature file and the code it describes end up evolving together without the specification-vs-implementation gap that catches misaligned intent. Mitigation: writer’s sparse-checkout excludes implementation directories — structurally enforced, not merely conventional.
• Procedural gates survive review skill. Reviewer’s structural-enforcement audit missed a manual-checkbox gate or a prose rollback. The feature ships with a human-procedural bottleneck that the v0.27 rubric Corollary pushes against. Mitigation: the review skill’s prompt must name the specific anti-patterns (checkbox gates, no drift detection, prose rollback, runtime soft-fail state) as an explicit checklist, not leave them to the reviewer’s intuition.
• Scoping-brief divorce from feature file. <slug>-scoping-notes.md gets written but nobody looks at it after draft; meanwhile the feature file loses sync with the decisions the brief captured. Mitigation: the brief is named as a direct input in the draft skill’s handoff criterion, and review skill cross-checks the feature file against the brief’s locked decisions as one of its audit items.
• Review-notes ignored. Gap report produced but no iteration happens. Feature is committed with unresolved apply items. Mitigation: review-notes file’s presence with outstanding items blocks feature completion; apply items are either resolved via re-draft or explicitly converted to skip with rationale.
• Research brief under-specified. Field-agent returns thin findings because the brief didn’t name the load-bearing questions. Mitigation: the scope skill’s prompt includes a brief-writing template (context, prior decisions, primary sources to fetch, N specific questions, deliverable shape, scope discipline); briefs are reviewed before research commissioning.

Cost estimate

First deployment in a project: 1-3 days to set up the writer session (sparse-checkout config, CLAUDE.md for the session, skill prompts / slash commands if that’s the instantiation). Mostly one-off per canon.

Per ordinary feature (1-2 research topics, single feature, no decomposition): ~3 hours of user time spread across skills (15-30 min shape-of-work dialogue, 10 min per research validation, 20-30 min architecture decisions, 30-60 min draft review, 30-60 min review-notes review). Research field-agents run in the background; elapsed calendar time is 1-3 days depending on user availability.

Per substantive feature (4-5 research topics, possible decomposition into sibling feature): ~5-8 hours of user time over 1-2 weeks elapsed. Decomposition adds a second loop through scope + draft + review for the extracted feature.

Ongoing maintenance: moderate. The recipe itself should be revisited quarterly — the skills’ prompts may drift from the recipe text as patterns emerge in practice, and the reconciliation is a PR. Review-notes files accumulate; a tidy pattern is to absorb them into the feature’s Retrospective at status: complete and delete the sidecar.

Open design questions

• Scoping-notes and review-notes persistence. Committed as sibling files (<slug>-scoping-notes.md, <slug>-review-notes.md) to support “resume days later” and post-ship retrospective analysis, or session-transient for cleaner feature directories? Current recommendation: committed and then folded into the feature’s Retrospective section on completion, then deleted. Not yet verified against an actual resume-after-week scenario.
• How cold is cold context for the review skill? /clear in the same session (fast, minimal), vs fresh session on a different day (stronger cold-start), vs explicit new-user-session for the reviewer (strongest but highest friction). Likely a tenant choice rather than recipe-mandated; but worth observed evidence from a few cycles.
• Test for legitimate research skip. “We’ve already researched this technology” is a fair skip; “the decision is obvious from existing references” is a weaker claim. What’s the tightest rule? Candidate: skip is legitimate when an existing research/ entry covers the current question with rubric_version within the last two rubric bumps — otherwise commission a light research pass.
• Research brief template extraction. The briefs written this recipe’s shakedown session converged on a shape (context / prior decisions / primary sources / N questions / deliverable / scope discipline). Worth extracting as recipes/_sub/research-brief.md or similar, or as a sub-section in this recipe? Deferred — extract after 2-3 more cycles if the shape remains stable.
• Writer-implementer handoff artefact. Is the feature file the complete handoff, or does the implementer need additional signals (build-order hints, test-first reminders, implementation-phase milestones)? Pass-1 assumes the feature file is sufficient. Revisit when the sibling recipe for implementation is drafted.
• Slash-command vs subagent-definition instantiation. Claude Code supports both; the recipe is agnostic. Tenant integration docs choose. Slash commands (/scope, /draft, /review) are lighter-weight; subagent definitions provide stronger context-scope enforcement. Pass-1 tenants will likely start with slash commands and graduate if the per-skill prompts prove stable enough to warrant isolated subagents.

Related recipes

• Composes with: recipes/ingestion-as-pr.md — research field-agents are a specific instantiation of the ingestion-as-PR pattern: external content (primary sources) is fetched by a narrowly-scoped agent and lands in the canon only via committed, reviewed artefacts. The trifecta boundary between feature-writer (holds canon) and research field-agents (holds untrusted web) is enforced by the same PR gate.
• Composes with: recipes/indexed-per-entry-registry.md — the feature artefacts this recipe produces live in an indexed registry; the scope skill’s inventory step walks those indexes as its canonical search surface. Without the registry discipline, “find related research” degrades to ad-hoc filesystem exploration.
• Alternatives to: informal feature-authoring practice where one session produces a feature file in a single pass, without skill boundaries, without commissioned research, without a separate review pass. What’s lost: retrievable scoping artefacts, primary-source-backed decisions, cold-context gap-finding, trifecta separation, clean handoff to implementer. Usable at very small scale (one-person project, low-stakes features) but doesn’t compound at portfolio scale.
• Depends on: recipes/indexed-per-entry-registry.md — the canon-taxonomy substrate the writer reads from.
• Future sibling: recipes/feature-implementation-loop.md (not yet drafted). Covers the feature-implementer role’s sparse-checkout, tool scope, workflow (test-first where specifiable, spike-exempt where not), and handoff from the feature file the writer produced. Together the two recipes constitute the writer → implementer chain for a feature’s full lifecycle.