ascent-feature-brief

name: ascent-feature-brief description: Creates concise feature briefs for handoff to Claude Code. Use when users want to document a feature for implementation, need a spec for coding, want to capture architecture decisions for handoff, or are planning features to be built by an AI coding agent. Generates token-efficient implementation directives that communicate intent while delegating schema discovery to the coding agent.

Feature Brief Generator

Create concise, token-efficient feature briefs that communicate implementation intent to Claude Code while delegating technical discovery to the coding agent.

Design Philosophy

Feature briefs are implementation directives, not detailed design specs. They:

• Communicate what to build and why, not how
• Set boundaries and constraints clearly
• Delegate schema/codebase discovery to Claude Code
• Preserve context window for actual implementation work

Brief Structure

Task List Link (When Available)

When a task list exists for the feature, include a link to it immediately after the title.

This creates bidirectional linking between the brief and task list for easy navigation in Obsidian.

# Feature Brief: [Feature Name]

**Task List:** [feature-name-tasks.md](feature-name-tasks.md)

Guidelines:

• Place the link on the line immediately after the main title
• Use Obsidian-compatible format: [filename.md] or [filename.md](filename.md)
• The filename should match the actual task list filename in the same folder
• Only add this link if a task list has been created
• This enables automatic linking in Obsidian and ensures traceability

Content Sections

Generate briefs using this structure:

1. Summary (2-3 sentences)

State what we're building and the core user value. Be specific about the outcome.

Good: "Add workout sync functionality that pulls completed workouts from HealthKit and stores them in the app's database. This enables users to see their training history without manual entry."

Weak: "Implement HealthKit integration for workouts."

2. User Stories (bulleted, concise)

Key workflows in "As a user, I can..." format. Focus on observable behaviors, not implementation.

- As a user, I can see my completed workouts from Apple Watch in the app
- As a user, I can view workout details including duration, distance, and heart rate
- As a user, I can manually refresh to pull latest workouts

Limit to 3-6 stories. If more are needed, the feature may need splitting.

3. Behavior & Rules

How the feature should work. Include:

• Core business logic
• Data flow (conceptually)
• Edge cases worth highlighting
• Error states and how to handle them

Write as prose or short bullets. Avoid implementation details—focus on what happens, not how it's coded.

Workouts sync on app launch and manual refresh. Only workouts completed after 
the user's account creation date should sync. Duplicate detection uses the 
HealthKit workout UUID. If a workout already exists, skip it silently.

For workouts without GPS data, distance may be nil—display "—" in the UI.

4. Boundaries

Explicit scope limits. What this feature does NOT do.

Out of scope:
- Real-time streaming of in-progress workouts
- Editing or deleting synced workouts
- Syncing to other platforms (Strava, Garmin)
- Background sync (manual/app-launch only for v1)

This prevents scope creep during implementation.

5. Implementation Guidance

Instructions for Claude Code. This is the prompt engineering section.

Standard template:

## Implementation Guidance

Before implementing:
1. Query the database schema to understand current table structures
2. Examine existing patterns in [relevant area/module]
3. Review how similar features handle [relevant concern]

Propose a plan before writing code. Include:
- Which tables/models will be created or modified
- Key functions or services needed
- How this integrates with existing code

[Any feature-specific technical hints, e.g.:]
- Use the existing HealthKitService for Apple Health integration
- Follow the medallion architecture pattern (Bronze → Silver → Gold)
- Coordinate with the existing sync queue for background operations

Adjust based on what's relevant to the feature.

Output Format

Present the brief in a clean, copy-paste-ready format with Obsidian-compatible YAML frontmatter:

---
status: not_started
priority: [high | medium | low]
agent: claude-code
created: YYYY-MM-DD
tags: [tag1, tag2]
---
# Feature Brief: [Feature Name]

**Task List:** [feature-name-tasks.md](feature-name-tasks.md) _(Add this link when task list is created)_

## Summary
[2-3 sentences]

## User Stories
- As a user, I can...
- As a user, I can...

## Behavior & Rules
[Prose describing how it works]

## Boundaries
Out of scope:
- [Item]
- [Item]

## Implementation Guidance
[Instructions for Claude Code]

YAML Frontmatter Fields

All feature briefs must include these frontmatter fields for Obsidian dashboard tracking:

Tags

Include relevant tags for cross-cutting concern filtering. Common tags:

Example with all fields:

---
status: in_progress
priority: high
agent: claude-code
created: 2025-12-12
started: 2025-12-15
tags: [ios, supabase, ai]
notes: |
  This feature depends on the workout sync infrastructure being complete.
  Priority: After hydration testing, before advanced dimensionality.
dependencies:
  - workout-sync (complete)
---

Minimal example (required fields only):

---
status: not_started
priority: high
agent: claude-code
created: 2025-12-12
started: 2025-12-12
tags: [ios, supabase]
notes: |
  Brief description of the feature.
---

Status transitions:

• New briefs start as not_started with created: YYYY-MM-DD
• When implementation begins, change to in_progress and add started: YYYY-MM-DD
• When ready for testing, change to testing
• Use blocked if waiting on external dependencies
• Use complete when feature is done and add completed: YYYY-MM-DD (before archiving)

Priority Requirements:

• Required for status: in_progress and status: not_started
• Optional for status: complete, status: testing, status: blocked
• Priority values: critical (highest) → high → medium → low (lowest)

Generating Briefs

When the user requests a feature brief:

1. Clarify scope if the feature is ambiguous—ask what's in/out before writing
2. Extract user value from the discussion—why does this matter?
3. Identify boundaries from what was discussed vs. deferred
4. Write concisely—every sentence should earn its tokens
5. Include discovery instructions appropriate to their codebase

File Location & Folder Creation

IMPORTANT: Create folder first (mkdir -p), then write brief file, confirm location.

Path: Docs/AscentTraining_Docs/features/[Feature-Name]/[feature-name]-brief.md

Naming: Folders Title-Case with hyphens, files lowercase with hyphens. Reference Docs/AscentTraining_Docs/README.md for structure.

Quality Checklist

Before delivering a brief, verify:

• YAML frontmatter includes status, priority, agent, and created fields
• Task list link is added at the top when a task list exists (using Obsidian format [filename.md])
• Summary states clear user value, not just technical action
• User stories describe observable behaviors
• Behavior section covers happy path AND edge cases
• Boundaries explicitly list what's out of scope
• Implementation guidance tells Claude Code what to discover
• Total length is under ~400 words (token-efficient)
• No implementation details that Claude Code should discover itself
• File saved in Docs/AscentTraining_Docs/features/[Feature-Name]/

Post-Creation Updates

Note: Dashboard auto-tracks file modification times. No manual last_worked updates needed.