Add step-retrospective reasoning protoco

[abeltrano]

Summary

Adds a step-retrospective reasoning protocol — a systematic methodology for learning from execution experience in iterative workflows. After completing a step, the protocol drives analysis of what happened, why it diverged from expectations, and what concrete improvements to feed back into the tooling and
process.

Closes #122

Why This Protocol?

PromptKit has protocols for quality-gating (self-verification), multi-agent evaluation (workflow-arbitration), and document revision (iterative-refinement). But none address the feedback loop: converting execution experience into tooling improvements for the next iteration.

Without this, iterative workflows repeat the same mistakes. With it, each step makes the next one better — the agent, scripts, and checklists improve as the workflow progresses.

The 5 Phases

Phase	Purpose	Output
Outcome Assessment	Quantitative comparison of actual vs expected	Metrics table
Variance Analysis	Classify each deviation (tooling/process/knowledge/external)	Categorized findings
Root Cause Identification	5-whys to trace fundamental cause	Root cause per finding
Feedback Action Planning	Concrete, file-targeted improvements with priorities	Action table (block/improve/defer)
Apply and Verify	Execute priority actions, verify, commit	Improved tooling

New Components

Just 1 protocol — everything else is reused:

Component	Type	File
step-retrospective	reasoning protocol	protocols/reasoning/step-retrospective.md

Key Design Decisions

• Protocol, not template: This is a reusable reasoning methodology, not a task-specific prompt. Any iterative template can reference it.
• 4 variance categories: Tooling gap, process gap, knowledge gap, external factor — covers all root cause types encountered in practice.
• 3 action priorities: block (must fix now), improve (should fix), defer (document for later) — prevents both under-fixing and over-fixing.
• Anti-patterns section: Explicitly rejects vague findings, vague actions, blame attribution, and documentation theater (recording without applying).
• Quantitative emphasis: Metrics first, interpretation second — prevents subjective retrospectives.
• Domain-agnostic examples: Variance category examples span linting, deployment, testing, CI, and API design — not tied to any specific project.

Origin

Developed during a Cilium fork synchronization effort where 8 iterative merge steps each produced findings (verifier issues, struct layout mismatches, build system gaps, test infrastructure problems) that were fed back into the merge agent, devtest scripts, and safety nets. The protocol formalizes what was
done ad-hoc into a repeatable methodology.

Validation

• SPDX headers present (MIT, PromptKit Contributors)
• YAML frontmatter valid and complete
• File name is kebab-case matching name field
• Protocol has numbered, ordered phases with specific checks
• No vague instructions — every step is actionable
• manifest.yaml updated with correct entry
• Does not duplicate or conflict with existing protocols
• applicable_to references valid template names
• LF line endings (normalized from CRLF)

[Copilot]

Pull request overview

Adds a new reusable reasoning protocol to PromptKit for running structured post-step retrospectives in iterative workflows, and registers it in the library manifest so it can be discovered/assembled by the bootstrap engine.

Changes:

• Added step-retrospective reasoning protocol with 5 explicit phases (outcome → variance → root cause → actions → apply/verify).
• Updated manifest.yaml to include the new protocol under protocols.reasoning.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
protocols/reasoning/step-retrospective.md	New reasoning protocol describing a step-level retrospective methodology and action feedback loop.
manifest.yaml	Registers the new protocol so it’s discoverable by PromptKit’s component manifest.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.