You are tasked with creating comprehensive implementation summaries that document completed work. These summaries capture what was changed and why, serving as permanent documentation for future developers and AI coding agent instances.
/plugin marketplace add mchowning/claude-code-plugins/plugin install workflow-tools@mchowning-marketplaceYou are tasked with creating comprehensive implementation summaries that document completed work. These summaries capture what was changed and why, serving as permanent documentation for future developers and AI coding agent instances.
Arguments: $ARGUMENTS
CRITICAL: Before running any bash commands, gather all required information. First check if the user already provided information, then only ask about missing pieces.
Analyze $ARGUMENTS and user's prompt for pre-provided information:
Check $ARGUMENTS above and the user's initial prompt for each of these three pieces of information:
| Information | How to Detect |
|---|---|
| Context documents | File paths like working-notes/*.md, plans/*.md, or explicit references like "using the plan at..." |
| Jira ticket | Pattern matching [A-Z]+-[0-9]+ (e.g., PROJ-1234, ABC-567) |
| Git diff scope | Keywords: "default branch", "from main", "from master", "most recent commit", "last commit", "uncommitted changes", or a custom git range |
Store any detected values for use in later steps.
Ask only about missing information:
If ALL three pieces of information were provided in the user's prompt, skip to step 3.
Otherwise, use AskUserQuestion with ONLY the questions for information that was NOT detected:
Question - Context Documents (only if not detected):
Question - Jira Ticket (only if not detected):
Question - Git Diff Scope (only if not detected):
Store all values:
Determine the default branch:
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'DEFAULT_BRANCHCheck for uncommitted code changes (skip if user chose "Uncommitted changes"):
git status to check for uncommitted changesworking-notes/, notes/, or ending in .md)You have uncommitted code changes. Consider committing your work before generating implementation documentation.
Uncommitted changes:
[list the uncommitted code files]
Execute the git diff command based on user's answer:
git diff [DEFAULT_BRANCH]...HEADgit diff HEAD~1 HEADgit diff HEADFetch Jira ticket details (if applicable):
workflow-tools:jira agent to fetch ticket details: "Get details for Jira ticket [TICKET-NUMBER]"Read provided documentation fully:
For uncommitted changes: Only collect basic metadata:
${CLAUDE_PLUGIN_ROOT}/skills/frontmatter/workflow-tools-frontmatter.shgit_commit will be the current HEAD, not the uncommitted changes themselvesFor committed changes: Collect full metadata:
Collect frontmatter metadata using the agent:
${CLAUDE_PLUGIN_ROOT}/skills/frontmatter/workflow-tools-frontmatter.shCollect comprehensive git metadata: Run these commands to gather commit information:
git log --oneline --no-decorate <range>git log --format="%H%n%an%n%ae%n%aI%n%s%n%b" <range>gh pr view --json number,url (may not exist yet)git merge-base [DEFAULT_BRANCH] HEADDetermine commit range context:
Skip this step entirely for uncommitted changes.
For committed changes:
git branch -r --contains HEADhttps://github.com/{owner}/{repo}/blob/{commit})Prepare the document filename:
notes/YYYY-MM-DD_descriptive-name.mdWrite the implementation summary using this strict template:
---
date: [Use date from frontmatter-generator (Step 4)]
git_commit: [Use git_commit from frontmatter-generator (Step 4)] # Omit this field for uncommitted changes
branch: [Use branch from frontmatter-generator (Step 4)]
repository: [Use repository from frontmatter-generator (Step 4)]
jira_ticket: "[TICKET-NUMBER]" # Optional - include if Jira ticket provided in Step 1
topic: "[Feature/Task Name]"
tags: [implementation, relevant-component-names]
last_updated: [Extract YYYY-MM-DD from frontmatter date field]
---
# [Feature/Task Name]
## Summary
[1-3 sentence high-level summary of what was accomplished]
## Overview
[High-level description of the changes, written for developers to quickly understand what was done and why. This should be readable in a few minutes. Minimal code citations and quotations - only include them if central to understanding the change. Focus on the business/technical goals and how they were achieved.]
## Technical Details
[Comprehensive explanation of the changes with focus on WHY. This is NOT just a recitation of what changed (that's available in the git commits). Instead, explain:
- What the purpose was behind the different changeds
- Why these specific changes were chosen to accomplish those goals
- Key design decisions and their rationale
- How different pieces fit together
For the most important changes, include code quotations to illustrate the implementation. For moderately important changes, include code references (file:line). Small changes like name changes should not be referenced at all.]
### [Component/Area 1]
[Explain what was changed in this component and why these changes accomplish the goals. Include code quotations for the most important changes. There should almost always be at least one code change quotation for each component/area:]
```[language]
// Most important code change
function criticalFunction() {
// ...
}
```
[For moderately important changes, use code references like `path/to/file.ext:123`]
### [Component/Area 2]
[Similar structure...]
[Add additional sections as necessary for additional Components/Areas]
## Git References
<!-- FOR UNCOMMITTED CHANGES: Use this simplified section -->
**Branch**: `[branch-name]`
**Status**: Uncommitted changes
<!-- FOR COMMITTED CHANGES: Use this full section instead -->
**Branch**: `[branch-name]`
**Commit Range**: `[base-commit-hash]...[head-commit-hash]`
**Commits Documented**:
**[commit-hash]** ([date])
[Full commit message including body]
[If on main branch or commits are pushed, include GitHub permalink to files]
**[commit-hash]** ([date])
[Full commit message including body]
[Continue for all commits in the range...]
**Pull Request**: [#123](https://github.com/owner/repo/pull/123) _(if available)_
<!-- END CONDITIONAL SECTION -->
This step must be completed before presenting the document to the user.
Check if external review is configured:
echo "${CLAUDE_EXTERNAL_REVIEW_COMMAND:-NOT_SET}"
If the variable shows NOT_SET or is empty:
If external review IS configured:
The environment variable contains one or more review commands separated by : (colon-space).
Examples:
opencode --model github-copilot/gpt-5 runopencode --model github-copilot/gpt-5 run: opencode --model deepseek/deepseek-v3 runFor each review command (process them sequentially):
Extract the command (split on : delimiter if multiple)
Run the external review: Execute the command with this review prompt:
${COMMAND} "Review the implementation summary at [DOCUMENT_PATH] and provide detailed feedback on:
1. Accuracy of the technical explanation - does it correctly explain what was implemented and why?
2. Completeness - are there important changes that were omitted from the summary?
3. Clarity - will another developer understand what was done and why from reading this?
4. Missing context - are there important decisions, constraints, or rationale that should be documented?
5. Factual errors - are there any incorrect statements about what the code does?
6. Missing git references - are all relevant commits properly documented?
Be specific about what's missing or incorrect. Focus on ensuring the summary accurately and completely documents the implementation work."
Analyze feedback with extreme skepticism:
Silently address ONLY critical issues:
If multiple reviewers: Each subsequent reviewer sees the updated document from the previous review
Do NOT present reviews to the user - this is an internal quality check.
The implementation summary has been written and quality-checked. Ready to present to user.
I've created the implementation summary at: `notes/YYYY-MM-DD_descriptive-name.md`
Stage and commit the summary document:
git add with the specific file path (never use -A or .)Add implementation summary for [Feature/Task Name]
Documents the changes made for [brief description of what was implemented].
Execute the commit:
git add notes/YYYY-MM-DD_descriptive-name.md
git commit -m "$(cat <<'EOF'
Add implementation summary for [Feature/Task Name]
[Brief description of what the summary documents]
EOF
)"
Show the result:
git log --oneline -n 1 to confirm the commit was createdworkflow-tools:jira agent to fetch ticket details when availableThe implementation summary is complete when:
notes/YYYY-MM-DD_descriptive-name.md