Backtrail Create Feature

Purpose

Create FEATURE documentation only. Inspect code as needed, but write only FEATURE docs and .backtrail/features.md.

FEATURE records describe user-visible capability, product behavior, workflows, and acceptance criteria that benefit from durable capability specs.

Input

Use the text after this skill invocation as the feature brief.

Resources

• Use assets/feature-template.md as the FEATURE template.

Statuses

• Allowed statuses: Proposed, Accepted, Rejected, Implemented.
• Create step writes Proposed; reserve Implemented for completed implementation.

Workflow

1. If the brief does not identify user-visible capability or product behavior, ask for the feature topic before creating files.
2. Read .backtrail/features.md, related FEATURE, ADR, and CHANGE docs, and relevant code. If .backtrail/features.md or .backtrail/features/ is missing, plan to create it.
3. Apply the FEATURE gate before creating files.
   • Create FEATUREs only for user-visible capability, product behavior, workflow, or acceptance criteria needing a durable capability spec.
   • Route durable architecture choices to backtrail-create-adr when brief constrains future work or changes architecture, repository structure, public contracts, generated output, build/test workflow, dependencies, or reversibility.
   • Route concrete implementation work with no feature-spec need to backtrail-create-change.
   • If the gate fails, stop and explain which artifact fits better. Do not create FEATURE files.
4. Determine the FEATURE number.
   • Use an explicit number only when it appears at the start of input, after optional whitespace.
   • Supported prefixes: FEATURE-014, FEATURE 014, F-014, #14, #014, 014, 14.
   • Normalize to five digits: #14 Export runs -> FEATURE-00014, .backtrail/features/feature-00014-export-runs.md.
   • Do not scan the input body for FEATURE numbers.
   • If no starting number exists, use the highest FEATURE-NNNNN from .backtrail/features.md + 1.
   • If .backtrail/features.md is missing, create it and start at FEATURE-00001 unless the brief has an explicit starting number.
5. Stop if .backtrail/features/feature-NNNNN-title-slug.md already exists.
6. Assess whether dedicated rollback detail is required. Require it when the capability:
   • destroys or irreversibly transforms data;
   • creates a public contract or compatibility break;
   • changes authentication, authorization, security, billing, or financial behavior;
   • requires a migration, compatibility window, coordinated deployment, or manual recovery; or
   • would be materially costly, risky, or operationally complex to reverse.
7. Present rough approach before writing.
   • capability
   • users/use cases
   • scope and non-goals
   • acceptance criteria
   • dependencies
   • independent risks, when useful
   • rollback assessment and, only when a trigger applies, the reversal or recovery plan
   • related FEATUREs/ADRs, if any
8. Ask only questions that change capability, users, scope, compatibility, acceptance criteria, dependencies, or a required reversal or recovery plan.
9. Create .backtrail/features/feature-NNNNN-title-slug.md from assets/feature-template.md.
   • Add a dedicated ## Rollback section only when a trigger in step 6 applies.
   • Omit the section rather than filling it with generic text when no trigger applies.
   • Add separate risk analysis when useful without adding ## Rollback solely for that analysis.
10. Save the FEATURE and its .backtrail/features.md entry with status Proposed.
11. Ask whether to promote to Accepted or Rejected.
    • Use three choices when request_user_input is available: Accepted, Rejected, Leave Proposed.
    • Accepted: update status in the FEATURE and .backtrail/features.md.
    • Rejected: update status in the FEATURE and .backtrail/features.md.
    • Leave Proposed: leave Proposed.
12. Offer to proceed with creating a CHANGE after FEATURE creation.
    • Use Yes/No buttons when request_user_input is available.
    • Yes: use backtrail-create-change.
    • No: skip to the next step.
13. Stop after docs/status changes. Do not implement code.

Question UX

• Use request_user_input when available for two or three meaningful choices.
• For yes/no decisions, present Yes and No choices.
• For FEATURE status after creation, present Accepted, Rejected, and Leave Proposed choices.
• If request_user_input is unavailable, ask one concise plain-text question with numbered choices.
• Do not claim that a skill can switch modes or force button rendering.

Guardrails

• Do not change implementation code, non-FEATURE templates, configs, or tests.
• Do not overwrite existing FEATURE files.
• Do not create ADR or CHANGE records directly; use the matching Backtrail creation skill.
• Do not treat numbers in input body as FEATURE numbers.
• Do not mark FEATURE as Implemented during creation. Set it later when implementation CHANGE records finish.
• Superseding or replacing another FEATURE requires explicit user confirmation.