Retrospective Artifacts

Retrospective Artifacts

Overview

Create durable, queryable retrospective artifacts under .retrospectives/ and provide deterministic retrieval of key learnings from prior artifacts.

This skill has two modes:

• CREATE mode: interview, gather context, and build a standardized retrospective folder.
• PARSE mode: read existing retrospective folders and return only the requested facts.

Routing

Use CREATE mode when the request asks to:

• run a retrospective
• capture session learnings
• build a retro artifact folder
• summarize current work and preserve context

Use PARSE mode when the request asks to:

• query previous retrospectives
• extract specific learnings/code snippets/logs
• shortlist okb_worthy items
• find sessions needing context asset improvement

Workflow 1: CREATE mode

Follow these steps in order.

Step 1: Context triage

1. Inspect current conversation and workspace context.
2. Identify missing facts: catalyst, impact, investigation, resolution, and downstream signals.
3. Use references/context-intake-checklist.md to drive coverage.

Step 2: Progressive interview

Ask 1-3 targeted questions to fill missing gaps. Always request relevant external links if available:

• GitHub issues/PRs/Actions logs
• Jira tickets
• Mattermost threads
• external incident docs

Before extraction, require a focus directive from the user to control what gets exported from large contexts. Accept examples like:

• "only moments where Copilot iterated 3+ times"
• "only failed attempts and workarounds"
• "only final solutions and why they worked"
• "exclude routine successful steps"

Do not proceed to generation until the required minimum context is present.

Step 3: External context acquisition

For each provided link:

1. Prefer MCP integrations first (GitHub/Jira/Mattermost MCP servers when available).
2. If MCP is unavailable for a source, use fallback scripts in scripts/.
3. If retrieval fails or access is denied, state that clearly and request pasted text.
4. Do not infer missing external content.

By default, perform bounded recursive gathering:

• discover first-level referenced URLs in fetched content
• acquire relevant linked artifacts (GitHub/Jira/Mattermost/docs) when they add incident value
• stop at one recursive level unless user explicitly asks for deeper traversal
• respect focus directive to avoid low-signal expansion

Use references/context-intake-checklist.md and references/external-context-acquisition.md as mandatory guidance.

Step 3.1: Markdown summary quality gate

Any acquired context saved as markdown must include an explicit, high-signal summary section near the top.

Minimum requirement:

• ## Summary

Summary quality expectations:

• 3-7 concise bullets or short paragraphs
• include what changed, why it mattered, and key technical signals
• prioritize incident-relevant facts over low-signal detail

When using MCP for retrieval, enforce this summary section before finalizing the artifact.

Step 4: Artifact generation

Create a timestamped folder under: .retrospectives/YYYY-MM-DD_short-session-name/

Expected structure:

• retro-summary.md
• context/ (external threads/docs)
• logs/ (errors, traces, diagnostics)
• code-snippets/ (before/after or key snippets)

Use references/retro-summary-template.md as the required output schema. Ensure the generated summary clearly states the selected focus directive and what was intentionally excluded.

Step 5: Quality gate

Before finalizing:

1. Validate frontmatter is complete and truthful.
2. Ensure all referenced relative paths exist.
3. Set downstream flags (okb_worthy, context_asset_improvement_needed) conservatively from evidence.
4. Never fabricate snippets, logs, or external thread content.

Workflow 2: PARSE mode

When asked to retrieve past information:

1. Locate matching folders in .retrospectives/.
2. Read retro-summary.md first.
3. Use references/parse-query-patterns.md to map request type to extraction strategy.
4. If requested data points to relative files (for example in context/, logs/, code-snippets/), open only those files.
5. Return only requested information with concise synthesis.

Do not dump full directories unless explicitly requested.

Output contract

• For CREATE mode, output:
  • artifact path
  • generated file index
  • concise summary of captured catalyst, resolution, and downstream signals
• For PARSE mode, output:
  • direct answer to query
  • supporting artifact path(s)
  • confidence caveat when data is missing or inaccessible

Constraints

• Anti-hallucination: never invent context, logs, or links.
• Path discipline: use explicit relative paths inside artifacts.
• Evidence-first tagging: set metadata flags from observable evidence.
• Non-destructive behavior: read/summarize existing retros by default.
• Integration priority: MCP servers first, local scripts second.
• Fallback scripts must fail loudly with explicit setup instructions when dependencies/tokens are missing.

References

• references/context-intake-checklist.md
• references/retro-summary-template.md
• references/parse-query-patterns.md
• references/external-context-acquisition.md

Manual fallback handoff

When acquisition fails after MCP + script fallback, use the baked-in handoff format in references/external-context-acquisition.md and request user-provided raw context.

Script fallback quick reference

Only use these scripts when MCP is unavailable for the source.

• GitHub URL fetch:
  • python3 scripts/fetch_github_context.py --url "<github-url>" --output "<artifact>/context/github-*.md"
• Jira issue fetch:
  • python3 scripts/fetch_jira_context.py --url "<jira-url>" --output "<artifact>/context/jira-*.md"
• Mattermost thread fetch:
  • python3 scripts/fetch_mattermost_thread.py --thread "<mm-thread-url-or-id>" --output "<artifact>/context/mm-*.md"