refine-story-technically

Refines user stories technically using Salesforce metadata dependency graphs and local backlog persistence.

Updated Dec 1, 2025
One-click install
npx skills add https://github.com/jterratsdev/smart-deployment --skill refine-story-technically-jterratsdev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: refine-story-technically
Source: https://github.com/jterratsdev/smart-deployment/tree/main/.setup-agents/skills/refine-story-technically
Command: npx skills add https://github.com/jterratsdev/smart-deployment --skill refine-story-technically-jterratsdev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Technical refinement of user stories often misses hidden metadata dependencies, causing broken deployments and untracked impact. This Skill runs impact analysis against a Salesforce metadata dependency graph, enforces naming conventions, breaks stories into technical tasks, and persists everything to a repo-resident backlog. ## Core Features & Use Cases - Metadata Impact Analysis: Detects the sf-graphify plugin or falls back to the built-in sf-metadata-index to query transitive dependencies and dependents for every component a story touches. - NAMING Convention Enforcement: Applies PascalCase API naming with mandatory descriptions and checks for collisions against existing metadata entries. - Local Backlog Persistence: Stores refined stories and technical tasks in the repo-resident .setup-agents/state/tasks.jsonl via sf setup-agents task create, keeping git as the source of truth. - Use Case: A Technical Architect refining a story that adds a field to the Account object uses this Skill to identify all dependent Apex classes and flows, generate technical tasks covering sharing and async implications, and record the refined story in the local backlog for QA regression targeting. ## Quick Start Ask the agent to technically refine a specific user story by running metadata impact analysis and saving the resulting technical tasks to the local backlog.

Frequently Asked Questions about refine-story-technically

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run impact analysis on Salesforce metadata before refining a story?

Impact analysis queries a metadata dependency graph for dependents and dependencies of each component the story touches. The Skill detects the sf-graphify plugin first, otherwise it builds the in-house sf-metadata-index with `sf setup-agents index` and queries it via MCP tools.

What happens if the sf-graphify plugin is not installed?

The Skill falls back to the in-house sf-metadata-index, which is the always-available default path. Running `sf setup-agents index` builds `.setup-agents/sf-metadata-index.json`, and the dependency_graph and query_metadata MCP tools provide the impact data.

Does this Skill write refined stories to Jira?

No, refined stories are persisted to the repo-resident backlog at `.setup-agents/state/tasks.jsonl` using `sf setup-agents task create`. Atlassian MCP mirroring is optional, but the local git-backed backlog remains the authoritative source.

What naming convention does technical refinement enforce?

The NAMING convention requires PascalCase API names with mandatory descriptions for every new component. Names are validated against the metadata graph via query_metadata to prevent collisions with existing entries.

When is a story handed off to decomposition instead of tasking?

A story is handed to the decompose step when it is still too large after technical tasking. The refinement process breaks stories into tasks covering impacted objects, sharing model, async considerations, and test strategy first.