Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Before producing the final artifact, confirm required inputs, target audience, missing facts, output format, and constraints when they are unclear. Do not invent missing information. Ask concise clarification questions when required inputs are absent.

• Skill name:

  ai-sdlc-goal-capability-and-epic-mapping

• Primary audience: PM
• Supporting audience: BA, Delivery
• Audience tags: PM, BA
• SDLC stage: Planning architecture
• Purpose: Turn a clarified initiative package into a structured planning model of goals, roles, capabilities, and epics.
• Output: Goal-to-capability map and outcome-oriented epics

• Clear business goals and target users.
• Validated initiative scope or PRFAQ/BRD input.
• Known outcomes, constraints, and priority signals.

• Ask concise questions before finalizing when role, artifact, requirements, scope, audience, or constraints are unclear.
• If optional information is missing, mark it as

  TBD

  ,

  Not provided

  , or

  Assumption

  instead of inventing it.
• Separate confirmed facts from assumptions and open questions.
• Do not proceed to downstream synthesis when a required upstream artifact or decision is missing.

• Support two explicit execution flags:

  --quick-flow

  and

  --full-flow

  .
• If both flags are supplied,

  --full-flow

  takes precedence because it is the stricter mode.

• --quick-flow

  : move fast, make high-quality progress with available context, avoid clarification questions unless continuing would create material product, security, compliance, data-loss, or irreversible implementation risk.
• In

  --quick-flow

  , use documented assumptions, recommended defaults, existing repository patterns, and the nearest available artifact evidence; record important assumptions and decisions in

  decision-log.md

  .
• In

  --quick-flow

  , run only focused checks that are directly relevant, cheap, and likely to catch regressions for the requested work; report any skipped broader checks as residual risk.

• --full-flow

  : ask concise clarification questions when inputs, scope, ownership, acceptance criteria, or decisions are unclear; do not silently assume material requirements.
• In

  --full-flow

  , verify upstream and downstream artifacts, decision-log entries, traceability links, acceptance criteria, and validation evidence before finalizing.
• In

  --full-flow

  , run or recommend the skill-appropriate gates, reviews, scripts, and validation commands needed for end-to-end confidence; document any blocked verification explicitly.
• When neither flag is supplied, follow the skill default rules and choose the least risky behavior for the request size and domain.

• Keep output structured with headings and bullets.
• Make findings, gaps, risks, and blockers explicit.
• Tie recommendations to evidence from the provided artifact,

  specs-refiniment/<feature-name>/<file.md>

  workspace, or user context.
• Include role ownership when the output creates follow-up work for BA, QA, Dev, PM, or Delivery.
• Return progress, completion, validation, and handoff summaries directly in the Codex response.
• Before the final response, emit the

  ai-sdlc-handoff/v1

  contract with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; every action includes

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or another standalone summary file unless the user explicitly requests one.
• Keep durable writes limited to the canonical lifecycle artifacts, decision log, human-readable index, and

  _ai_sdlc

  machine files.
• Let shared helpers migrate legacy paths on the next write; never overwrite or manually merge divergent legacy and canonical files.

• Maintain a feature decision log whenever this skill records, resolves, changes, or depends on a product, delivery, QA, security, validation, branching, implementation, or rollout decision.
• For PM, BA, QA, Delivery, discovery, planning, refinement, and readiness work, write decisions to

  specs-refiniment/<feature-name>/decision-log.md

  .
• For developer implementation SDD work, write decisions to

  specs/<feature-name>/decision-log.md

  .
• Each decision-log entry must include date, decision, context or evidence, options considered when relevant, owner, status, and links to affected artifacts, tasks, tests, or validation evidence.
• Use this exact decision-log structure:
  markdown

  # Decision Log
  
  | ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
  | --- | --- | --- | --- | --- | --- | --- | --- | --- |
  | DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

• When writing or updating files, place PM, BA, QA, Delivery, discovery, planning, refinement, and readiness artifacts at

  specs-refiniment/<feature-name>/<file.md>

  .
• Use the path pattern

  specs-refiniment/<feature-name>/<file.md>

  ; choose a stable feature slug when known, otherwise use

  tbd-<short-topic>

  for

  <feature-name>

  .
• Do not write this skill's output into

  specs/

  ; that folder is reserved for developer implementation SDD artifacts.
• If the user explicitly asks to convert a refined artifact into developer implementation work, hand off to

  $ai-sdlc-sdd

  .

• Maintain feature lifecycle state in TOON at

  specs-refiniment/<feature-name>/_ai_sdlc/state.toon

  for refinement work and

  specs/<feature-name>/_ai_sdlc/state.toon

  for implementation work.
• Before executing this skill for a feature, check the state machine with

  python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

  .
• When this skill starts durable work, mark it in progress with

  begin

  ; when the skill's required artifact or review is complete, mark it done with

  complete

  and include

  --artifacts <path>

  plus

  --decision-ref DEC-###

  when a decision was involved.
• In

  --full-flow

  , do not proceed when predecessor stages are incomplete, another lifecycle skill is active, or the state file reports a blocker.
• In

  --quick-flow

  , a predecessor skip is allowed only when continuing is low risk and the command includes

  --assumption "..."

  or

  --decision-ref DEC-###

  ; record the same assumption or decision in

  decision-log.md

  .
• Use

  python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

  to emit compact LLM-readable state before choosing the next skill.
• The state machine is feature-scoped: do not reuse a

  state.toon

  across unrelated feature folders.

• Every Markdown artifact generated or updated by this skill must start with an

  artifact_metadata

  YAML frontmatter block before the first visible heading.
• Use schema

  ai-sdlc-artifact-metadata/v1

  and keep these fields current:

  feature

  ,

  artifact

  ,

  path

  ,

  workspace

  ,

  skill

  ,

  flow_mode

  ,

  state_file

  ,

  decision_log

  ,

  status

  ,

  owner

  ,

  created_at

  ,

  updated_at

  ,

  trace_ids

  ,

  related_artifacts

  ,

  validation

  , and

  metatags

  .

• metatags

  must include at minimum

  ai-sdlc

  , the workspace (

  refinement

  or

  implementation

  ), this skill name, the artifact type or filename stem, and a lifecycle/status tag such as

  draft

  ,

  review

  ,

  approved

  , or

  validated

  .
• When

  --quick-flow

  is active, set

  flow_mode: quick

  , keep assumptions visible in the body, and add tags for major defaults or unresolved risk only when they help retrieval.
• When

  --full-flow

  is active, set

  flow_mode: full

  , keep blockers and validation evidence reflected in

  status

  ,

  validation

  ,

  trace_ids

  , and

  related_artifacts

  .
• Update metadata whenever the artifact path, status, owner, trace links, validation evidence, related artifacts, or decision references change.
• Metadata is an index for routing, retrieval, and traceability; it does not replace the artifact body,

  decision-log.md

  , or

  state.toon

  .

• Before searching across feature folders, inspect the compact LLM index first:

  specs-refiniment/_ai_sdlc/specs-index.toon

  for refinement work or

  specs/_ai_sdlc/specs-index.toon

  for implementation work.
• Use the human-readable index at

  specs-refiniment/specs-index.md

  or

  specs/specs-index.md

  when reporting feature coverage, artifact inventory, or handoff status to people.
• After this skill creates or materially updates an artifact, refresh the matching workspace index with

  python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

  .
• In

  --quick-flow

  , rely on

  specs-index.toon

  to choose the smallest relevant artifact set before opening files.
• In

  --full-flow

  , verify the updated artifact appears in both

  specs-index.toon

  and

  specs-index.md

  before final handoff.
• The specs index summarizes artifact metadata and state; it does not replace reading the selected source artifacts when details, approvals, or validation evidence matter.

• Trigger the complete cascade only when the user explicitly asks for a full, complete, or end-to-end spec refinement or asks for every refinement artifact. A normal

  --full-flow

  call for one skill remains single-stage.
• Before the first durable write, run

  python3 skills/_shared/refinement_status.py --feature <feature-name> --gate full --format toon

  and start with the earliest reported

  next_skill

  , including stages earlier than this skill.
• Execute the existing refinement skills in lifecycle order with

  --full-flow

  : discovery, PRFAQ, delivery-package gap review, requirements readiness, goal/capability mapping, backlog gap review, backlog decomposition, story decomposition, release slicing, BA context, delivery spec, QA plan, QA gap review, test strategy, test cases, test suite, QA readiness, and delivery handoff.
• Produce all 18 canonical Markdown artifacts.

  release-slicing.md

  is mandatory for a complete cascade; when release slicing is not applicable, write an explicit evidence-backed N/A artifact and complete the stage instead of skipping it.
• After every stage, finalize its artifact, record required decisions, mark the stage

  done

  , and refresh the refinement indexes before selecting the next skill.
• Do not declare the cascade complete until

  python3 skills/_shared/refinement_status.py --feature <feature-name> --gate full --format markdown

  exits successfully with

  18/18

  . If it fails, continue with the reported next skill or return the concrete blocker and remaining inventory in Codex.
• Surface checkpoint and final summaries in Codex only; never persist a cascade summary as a text file.

• Use

  scripts/goal_capability_map.py

  when deterministic scaffolding, planning, or formatting is useful for this workflow; pass the same

  --quick-flow

  or

  --full-flow

  flag that was supplied to the skill.
• Read

  references/mapping-structures.md

  when the task needs the detailed structure, checklist, or examples for this skill.

• In default and full flow, always run this skill's primary analysis script with

  --format toon --budget-tokens 24000

  before drafting; explicit inputs are priority evidence but do not replace the rest of the feature package.
• Read this skill's reference file before writing sections. Use its detailed tables and quality bar, not only the compact scaffold headings.
• Run the primary script with

  --emit-template

  in the active flow mode to obtain the exact shared context headings and required stage table columns before section writes.
• Make every default/full artifact self-contained by completing all ten shared feature-context sections plus the stage-specific profile sections. Quick flow may use the compact stage-only draft.
• Follow every

  next_reads

  entry before finalization and list every consumed source in

  Source Coverage

  ; do not claim whole-feature context from a partial source set.
• Keep the final artifact within

  --max-artifact-tokens 24000

  ; condense repetition instead of dropping feature dimensions or source traceability.
• Run

  scripts/goal_capability_map.py

  before drafting or updating this skill's artifact when inputs are longer than a few bullets, when traceability matters, or when a flow flag is supplied. For agent analysis, pass

  --format toon

  , read

  anchors

  first, and open only

  next_reads

  ; without that flag the script keeps its human-readable Markdown output.
• Quick flow analysis:

  python3 skills/ai-sdlc-goal-capability-and-epic-mapping/scripts/goal_capability_map.py --feature <feature-name> --quick-flow <input.md>...

• Full flow analysis:

  python3 skills/ai-sdlc-goal-capability-and-epic-mapping/scripts/goal_capability_map.py --feature <feature-name> --full-flow <input.md>...

• To write content, pass one canonical heading with

  --section "<section>"

  ; provide only that section body on stdin, without H1, H2, frontmatter, or a temporary content file.
• Repeat

  --section

  for each required section, then run the same script with

  --finalize

  to validate the artifact and refresh metadata and specs indexes.
• The AI must not write or directly edit the routed Markdown artifact; the script owns scaffold creation, section placement, and durable file writes.
• Use

  --decision-row

  with one nine-cell Markdown table row on stdin when a decision-log entry is required.
• Legacy

  --emit-template

  ,

  --emit-decision-log-entry

  , and

  --write

  remain available for compatibility.
• Use

  --quick-flow

  for first-pass synthesis with assumptions; use

  --full-flow

  before readiness, handoff, signoff, or any decision-sensitive output.

• The planning gap review is complete enough to proceed.
• The team needs structured planning layers before writing features and stories.

• Business outcomes or MVP boundaries are still unclear.
• The task only needs a lightweight feature list.

1. Define business goals and success criteria.
2. Identify users, roles, and actors with their planning-relevant needs.
3. Map the main product capabilities.
4. Group capabilities into outcome-oriented epics.
5. Capture dependencies, risks, and open questions at each level.

• Every goal should connect to at least one capability or required operational/compliance need.
• Every capability should support a user need, business goal, or delivery necessity.
• Every epic should have a clear outcome and be decomposable into smaller units.
• Do not allow miscellaneous or generic buckets that hide scope.

• Goals, roles, capabilities, and epics are explicit.
• The planning structure supports downstream feature/story decomposition.
• Weakly justified or over-broad planning areas are challenged and corrected.