ai-sdlc-research: Sourced Delivery Evidence

Optional domain skill, not required by the core module. Every rule below is important to follow. None of it can be skipped. Research informs decisions; it does not silently become a requirement or approval.

0. Skill Card

• Skill name:

  ai-sdlc-research

• Primary audience: Research, PM, BA, Architecture
• Supporting audience: Dev, QA, Security, Delivery
• Audience tags: Research, PM, BA, Architecture, Dev
• SDLC stage: Discovery, refinement, and design evidence
• Purpose: Preserve questions, sources, findings, confidence, and limitations.
• Output:

  research.md

  and

  _ai_sdlc/research.toon

0.1 Required Inputs

• Owning feature root.
• Research input using

  ai-sdlc-research-input/v1

  .
• Verifiable source locators and delivery trace targets.
• Internet access through the host web or browser tool for external or current questions.

0.2 Clarification Rules

• Ask when topic, decision to inform, source boundary, or freshness requirement is unclear.
• Separate sourced findings from inference and unresolved questions.
• Record contradictory sources and limitations; do not average them away.
• Do not claim current facts, legal conclusions, or user evidence without verification.

0.2.1 Flow Mode Flags

• Support

  --quick-flow

  and

  --full-flow

  ; full flow takes precedence.
• Quick flow permits one strong source when scope is explicitly narrow.
• Full flow requires at least two sources and two source types for each report.
• External and mixed scopes require an internet search and at least one direct

  http://

  or

  https://

  source locator; do not cite search-result pages.
• Both modes require every finding to cite registered sources and trace targets.

0.3 Output Rules

• Return question, source, finding, confidence, blocker, and output path counts directly in the Codex response.
• Before the final response, emit

  ai-sdlc-handoff/v1

  with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; every action includes

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or uncited research prose.
• Keep quotes within source rights and use concise paraphrase by default.

0.4 Artifact Routing

• Write

  <feature-root>/research.md

  .
• Write

  <feature-root>/_ai_sdlc/research.toon

  .
• Keep downloaded or licensed source files outside generated output unless allowed.
• Link research to requirements and decisions; do not overwrite them.

0.5 Feature State Machine

• Read

  <feature-root>/_ai_sdlc/state.toon

  before durable research writes.
• Research is optional and does not add a core lifecycle stage.

• --state-check

  is read-only;

  --begin-state

  and

  --complete-state

  are rejected.
• Accepted implications move through decisions, requirements, SDD, or change impact.

0.6 Artifact Metadata And Metatags

• Markdown starts with

  artifact_metadata

  using schema

  ai-sdlc-research-metadata/v1

  .
• Include

  metatags

  for

  ai-sdlc

  ,

  research

  ,

  evidence

  , and

  traceable

  .
• Record feature, workspace, flow mode, state file, trace IDs, and review status.

0.7 Specs Index

• Read the relevant

  specs/_ai_sdlc/specs-index.toon

  or

  specs-refiniment/_ai_sdlc/specs-index.toon

  before broad reads.
• Refresh the matching

  specs/specs-index.md

  or

  specs-refiniment/specs-index.md

  only after durable writes.
• Keep research inside the feature whose decisions it informs.

References

• Read

  references/research-contract.md

  for source and finding requirements.
• Read

  references/web-research-protocol.md

  before external or current research.
• Use

  scripts/research.py

  to validate citations and route canonical outputs.

Script Usage

python3 skills/ai-sdlc-research/scripts/research.py specs-refiniment/payments --input /tmp/research.json --emit --quick-flow
python3 skills/ai-sdlc-research/scripts/research.py specs/payments --input /tmp/research.json --write --full-flow --format toon

Purpose

Inputs

• Frame answerable questions connected to delivery traces.
• Register source title, locator, type, access date, credibility, and notes.
• Cite source IDs from each synthesized finding.
• Record confidence, limitations, and unresolved owner/action pairs.

Steps

1. Define the decision to inform, research questions, and

   internal

   ,

   external

   , or

   mixed

   evidence boundary.
2. For external or current questions, search the internet with the available web/browser tool, open direct result pages, compare publication and event dates, and prioritize primary or official sources.
3. Gather internal evidence when applicable and keep it distinguishable from web sources.
4. Register source identity, direct locator, access date, freshness, type, and credibility.
5. Synthesize findings separately from quotations and assumptions.
6. Record confidence, limitations, conflicts, and open questions.
7. Finalize routed Markdown and TOON outputs.
8. Route accepted implications through owning decisions and artifacts.

Output Spec

ai-sdlc-research/v1

• Pass when source IDs resolve, findings have confidence plus limitations, and delivery traces explain why the evidence matters.
• Full flow fails without two sources, two source types, or any open question owner.

Examples

SRC-001/SRC-003

DEC-022

Edge Cases

• A source may support and contradict different findings; keep both links.
• A blocked source remains registered only if its unavailability matters.
• Time-sensitive sources include an explicit access date and freshness limitation.
• Full flow source diversity counts distinct

  type

  values, not duplicate URLs.
• If internet access is unavailable for external scope, report a blocker and do not present cached model knowledge as completed research.

Scope Boundary

• Do not fabricate sources, quotes, dates, or research participants.
• Do not turn findings into accepted decisions or requirements automatically.
• Do not provide legal or regulatory conclusions without qualified review.
• Do not hide conflicting or low-confidence evidence.
• Use

  $ai-sdlc-change-impact

  when accepted research changes downstream artifacts.