chore: add Serena memories for GitHub workflow protocols#336
Conversation
- Add memory for GitHub issue assignment protocol - Add memory for PR template requirement These memories ensure consistent GitHub workflow behavior across sessions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Note Gemini is unable to generate a review for this pull request due to the file types involved not being currently supported. |
There was a problem hiding this comment.
Pull request overview
This PR adds two Serena memory files to establish persistent GitHub workflow protocols for AI agents. These memories ensure consistent behavior across sessions regarding issue assignment and PR template usage, supporting the workflow requirements introduced in PR #334.
Key Changes:
- Added memory for GitHub issue assignment protocol requiring self-assignment before starting work
- Added memory for PR template compliance with all required sections
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
.serena/memories/github-issue-assignment.md |
Establishes protocol for assigning GitHub issues to self before starting work using gh issue edit command |
.serena/memories/pr-template-requirement.md |
Documents requirement to use PR template at .github/PULL_REQUEST_TEMPLATE.md with all required sections |
|
Caution Review failedFailed to post review comments Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughLarge documentation reshuffle under .serena/memories: many new skill/memory docs added, several old memory files removed, multiple index files updated to map new skills, and CI workflow memory-validation.yml changed to use dynamic git-diff-based path detection instead of static path filters. (50 words) Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related issues
Possibly related PRs
Possibly related issues addressed by this PR
Suggested labels
Suggested reviewers
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
.serena/memories/github-issue-assignment.md (1)
1-23: Use prefix taxonomy for memory file naming.File should be named
pattern-github-issue-assignment.mdto follow the required prefix taxonomy for memory files (pattern-, context-, skill-, adr-). This helps agents discover and reference the memory correctly.Rename the file from
.serena/memories/github-issue-assignment.mdto.serena/memories/pattern-github-issue-assignment.md..serena/memories/pr-template-requirement.md (1)
1-38: Use prefix taxonomy for memory file naming.File should be named
pattern-pr-template-compliance.mdor similar to follow the required prefix taxonomy for memory files (pattern-, context-, skill-, adr-). This helps agents discover and reference the memory correctly.Rename the file from
.serena/memories/pr-template-requirement.mdto.serena/memories/pattern-pr-template-compliance.md.
📜 Review details
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.serena/memories/github-issue-assignment.md.serena/memories/pr-template-requirement.md
🧰 Additional context used
📓 Path-based instructions (6)
.serena/memories/**/*.md
📄 CodeRabbit inference engine (.agents/retrospective/pr43-coderabbit-root-cause-analysis.md)
Update memory/knowledge base snapshots when refined estimates or critical data diverges from previously stored values by more than 10%
.serena/memories/**/*.md: Skill memory files MUST include atomicity scores (>85% threshold required for persistence), evidence citations with specific session numbers, and SMART validation criteria (Specific, Measurable, Actionable, Relevant, Time-bound)
Skill deduplication analysis MUST be performed with similarity scoring (0-100%) before persistence, comparing new skills against existing memories and documenting the decision (ADD, UPDATE, or MERGE)
All skill memory entries MUST include source reference, validation count (number of times applied), and cross-references to related skills in other memory files
.serena/memories/**/*.md: Atomic memory files must contain focused, high-relevance content to minimize token waste during read operations; avoid consolidating multiple skills into single library files
Memory files and index statements must be designed for human readability and agent pattern recognition; avoid relying on unverified internal mechanisms like word frequency matchingCapture user insights about token efficiency and activation vocabulary in the
.serena/memories/directory for future referenceStore Skill-QA-007 (Verify-WorktreeIsolation.ps1) implementation and worktree isolation verification requirements in institutional memory at
.serena/memories/skill-qa-007-worktree-isolation.md
Files:
.serena/memories/pr-template-requirement.md.serena/memories/github-issue-assignment.md
**/.serena/memories/**/*.md
📄 CodeRabbit inference engine (.agents/sessions/2025-12-20-session-22.md)
Memory file names and index statements MUST contain dense, high-signal keywords because agents select memories based on word frequency matching
**/.serena/memories/**/*.md: Use semantic slugs for memory file naming instead of numeric IDs (e.g.,skill-git-squash-merge-clean-history.mdinstead ofSkill-Git-004.md)
Adopt prefix taxonomy for memory files:adr-[number]-[slug].mdfor architectural decisions,context-[domain]-[topic].mdfor domain knowledge,pattern-[problem]-[solution].mdfor recurring solutions,skill-[technology]-[technique].mdfor how-to guidesFor agent-facing patterns (detection, routing, decision logic), document in Serena memory FIRST using Skill-X-Y format in
.serena/memories/directory. Only write executable code if the pattern cannot be executed by agent reasoning alone. DO NOT create external shell scripts for pattern matching or detection logic.
Files:
.serena/memories/pr-template-requirement.md.serena/memories/github-issue-assignment.md
.serena/memories/**
📄 CodeRabbit inference engine (.agents/sessions/2025-12-20-session-48-semantic-slug-orchestration.md)
Commit all changes including
.serena/memoriesfiles as part of session completionCommit all changes including .serena/memories directory with session context
Commit all changes to
.serena/memoriesdirectory alongside code changes when updating session context and handoff informationCommit all changes including
.serena/memoriesdirectory before session closeDo not store ephemeral cache data (current open PRs, issues) in
.serena/memories/git-tracked files to preserve merge velocityAfter creating skill files and updating domain indexes, run the validation script 'pwsh scripts/Validate-MemoryIndex.ps1' to verify formatting, table structure, and file references are correct
Files:
.serena/memories/pr-template-requirement.md.serena/memories/github-issue-assignment.md
**/.serena/memories/*.md
📄 CodeRabbit inference engine (.agents/sessions/2025-12-20-session-38-pr-94-review.md)
Document discovered skills from retrospectives or code reviews with atomicity scores and evidence references in the skillbook
Files:
.serena/memories/pr-template-requirement.md.serena/memories/github-issue-assignment.md
{**/*.md,.serena/**}
📄 CodeRabbit inference engine (.agents/qa/002-pr-201-skills-clarity-fixes.md)
Provide concrete examples when documenting MCP tool naming conventions - include breakdown of server name and tool-id components
Files:
.serena/memories/pr-template-requirement.md.serena/memories/github-issue-assignment.md
.serena/memories/*-*.md
📄 CodeRabbit inference engine (.agents/critique/001-skillbook-documentation-critique.md)
.serena/memories/*-*.md: When creating a new skill file, use the naming convention: memory_file_name must follow domain-topic pattern (e.g., 'pr-skill-name', 'compliance-skill-name'), NOT the Skill ID format which is reserved for content inside the file
Skill ID format must be 'Skill-{Category}-{NNN}' where Category is 2-8 character abbreviation and NNN is a zero-padded 3-digit sequential number; determine NNN by searching existing skills in that category and incrementing the highest found number
Before committing a new Skill ID, verify uniqueness by searching all memory files to confirm the Skill ID does not already exist
Format A is for skills that are CRITICAL/BLOCKING or referenced by other skills (have BLOCKS/ENABLES relationships); use Format B for standalone, non-critical skills
A skill qualifies as CRITICAL/BLOCKING P0 if it meets ANY of these objective criteria: Impact score >= 9/10, blocks session protocol execution, prevents compliance violation, or requires high-level-advisor escalation
A skill is 'referenced by other skills' when it appears in Related Skills sections with BLOCKS/ENABLES relationships or is cited as a prerequisite for other skills
Skill category abbreviations must be 2-8 characters to balance readability in Skill IDs and avoid ambiguity with other category names
Skill format selection must follow the decision tree: (1) Is CRITICAL/BLOCKING P0? If yes → Format A; (2) Is referenced by other skills? If yes → Format A; (3) Otherwise → Format B
Atomicity scoring for skills must follow penalty structure: -2 for each unrelated responsibility, -1 for each optional substep, +1 for each integration point; minimum viable score is 3/10
Skill activation vocabulary (keywords that trigger the skill) must avoid words that appear in other skill names or activation vocabularies within the same category to prevent false matches
Files:
.serena/memories/pr-template-requirement.md.serena/memories/github-issue-assignment.md
🪛 LanguageTool
.serena/memories/pr-template-requirement.md
[uncategorized] ~5-~5: The official name of this software platform is spelled with a capital “H”.
Context: ...uest, always use the PR template at .github/PULL_REQUEST_TEMPLATE.md. ## Template...
(GITHUB)
🔍 Remote MCP DeepWiki
Additional Relevant Context
-
Established Memory Module
DeepWiki’s repository structure includes a “Serena Memory System” under “Session Protocol & Memory,” confirming that agent memories are stored in a dedicated.serena/memories/directory within the repo. -
Memory Operations
The Serena Memory System provides file-based memory management tools:
•write_memoryto create or overwrite a memory file
•read_memoryto retrieve contents from a memory file
•list_memoriesto enumerate all memory files
•delete_memoryto remove a memory file
•edit_memoryto update content via literal or regex replacement -
Mandatory Initialization
Before any memory operations, agents must callmcp__serena__activate_project(with the project path) andmcp__serena__initial_instructionsto initialize access to the memory system and related tooling. -
Memory Reference Guidelines
When instructing agents:
• MUST usemcp__serena__read_memorywith thememory_file_nameparameter (not file paths)
• MUST include a fallback to directly read the.serena/memories/<name>.mdfile if the MCP server is unavailable
• MUST NOT reference memories by full file path in instructions
• SHOULD use consistent syntax, e.g.:Read the `session-notes` memory using `mcp__serena__read_memory` with memory_file_name="session-notes" - If unavailable, read `.serena/memories/session-notes.md`
Comprehensive investigation of 20 open PRs to identify those stuck for similar reasons as PR #334. Key Findings: - PR #334 is NOT stuck (all checks pass, approved, mergeable) - 16 of 20 PRs are actually stuck - 10 PRs blocked by Aggregate Results failures (62.5%) - Only 1 PR (#342) shares PR #334's blocker type (missing workflow) - 6 PRs have merge conflicts - 3 PRs ready to merge immediately (#334, #336, #245) Analysis identifies systemic pattern in Aggregate Results failures affecting majority of stuck PRs, distinct from originally described missing workflow issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Comprehensive investigation of 20 open PRs to identify those stuck for similar reasons as PR #334. Key Findings: - PR #334 is NOT stuck (all checks pass, approved, mergeable) - 16 of 20 PRs are actually stuck - 10 PRs blocked by Aggregate Results failures (62.5%) - Only 1 PR (#342) shares PR #334's blocker type (missing workflow) - 6 PRs have merge conflicts - 3 PRs ready to merge immediately (#334, #336, #245) Analysis identifies systemic pattern in Aggregate Results failures affecting majority of stuck PRs, distinct from originally described missing workflow issue. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* fix(ci): remove path filters from memory validation workflow The 'Validate Memory Files' job is a required status check. With path filters at the workflow trigger level, the workflow doesn't run for PRs that don't touch memory files, causing those PRs to be blocked. Changes: - Remove path filters from on.push and on.pull_request triggers - Add comment explaining why path filters are not used - Fix git diff to use event-specific commit ranges - Properly split git diff output into array before filtering The change detection logic inside the job still skips validation for PRs that don't modify .serena/memories/** files. Fixes PRs being blocked by phantom 'Validate Memory Files' check. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(ci): add robust git diff handling for edge cases Address Copilot review comments: 1. Handle zero SHA when first commit on new branch 2. Detect force-push/rebase when before commit doesn't exist 3. Use two dots (..) for push events instead of three (...) 4. Add exit code check after git diff command Fallback to origin/main comparison when: - github.event.before is all zeros (first commit) - before commit no longer exists (force-push/rebase) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
* fix(memory): split bundled skill files per ADR-017 Split 18 bundled memory files into 49 atomic skill files to comply with ADR-017 requirement of one skill per file. Files processed: - documentation-fallback-pattern.md (2 skills) - documentation-migration-search.md (2 skills) - documentation-self-contained.md (2 skills) - implementation-test-discovery.md (2 skills) - iteration-5-checkpoint-skills.md (3 skills) - labeler-matcher-types.md (3 skills) - labeler-negation-patterns.md (2 skills) - phase3-consistency-skills.md (5 skills) - phase4-handoff-validation-skills.md (4 skills) - planning-self-contained.md (2 skills) - pr-review-bot-triage.md (4 skills) - pr-review-false-positives.md (2 skills) - security-defensive-coding.md (3 skills) - security-review-enforcement.md (2 skills) - security-toctou-defense.md (2 skills) - skills-agent-workflow-phase3.md (2 skills) - skills-edit.md (2 skills) - skills-governance.md (2 skills) Validation: pwsh scripts/Validate-SkillFormat.ps1 - PASSED 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(memory): update indexes to reference atomic skill files Update memory index files to point to the new atomic skill files created in the previous commit. Fixes broken references that caused Validate Memory Index to fail. Updated indexes: - memory-index.md - skills-documentation-index.md - skills-implementation-index.md - skills-labeler-index.md - skills-planning-index.md - skills-pr-review-index.md - skills-security-index.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(memory): restore bundled files for incomplete atomic split The previous commits attempted to split bundled skill files into atomic files per ADR-017 but the split was incomplete - only some atomic files were created while the index files were updated to reference all planned atomic files. This commit: - Restores bundled files from main (19 files) - Reverts index files to reference bundled files - Keeps successfully created atomic skill files Validate Memory Index now passes with 30/30 domains. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(memory): complete atomic skill split per ADR-017 Split 9 bundled skill files into 21 atomic skill files. Bundled files removed: - documentation-migration-search.md (skills 001, 002) - documentation-fallback-pattern.md (skills 003, 004) - documentation-self-contained.md (skills 006, 007) - implementation-test-discovery.md (skills 001, 002) - labeler-negation-patterns.md (skills 001, 006) - labeler-matcher-types.md (skills 003, 004, 005) - planning-self-contained.md (skills 003, 004) - pr-review-bot-triage.md (skills 001, 002, 003, 006) - pr-review-false-positives.md (skills 001, 002) Atomic skill files created: - skill-documentation-{001..004,006,007}-*.md - skill-implementation-{001,002}-*.md - skill-labeler-{001,003..006}-*.md - skill-planning-{003,004}-*.md - skill-pr-{001..003,006}-*.md - skill-review-{001,002}-*.md Index files updated with unique keywords per entry. Validates with both Validate-MemoryIndex.ps1 and Validate-SkillFormat.ps1. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: rjmurillo[bot] <rjmurillo-bot@users.noreply.github.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
…atus check (#346) * fix(ci): remove path filters from memory validation workflow The 'Validate Memory Files' job is a required status check. With path filters at the workflow trigger level, the workflow doesn't run for PRs that don't touch memory files, causing those PRs to be blocked. Changes: - Remove path filters from on.push and on.pull_request triggers - Add comment explaining why path filters are not used - Fix git diff to use event-specific commit ranges - Properly split git diff output into array before filtering The change detection logic inside the job still skips validation for PRs that don't modify .serena/memories/** files. Fixes PRs being blocked by phantom 'Validate Memory Files' check. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix(ci): add robust git diff handling for edge cases Address Copilot review comments: 1. Handle zero SHA when first commit on new branch 2. Detect force-push/rebase when before commit doesn't exist 3. Use two dots (..) for push events instead of three (...) 4. Add exit code check after git diff command Fallback to origin/main comparison when: - github.event.before is all zeros (first commit) - before commit no longer exists (force-push/rebase) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(retrospective): extract 7 atomic skills from PR #342 & #343 Retrospective of CI workflow debugging session that fixed phantom required check blocking. Analyzed PR #342 (initial fix) and PR #343 (comprehensive edge case handling). **Skills Extracted** (atomicity 88-95%): - Skill-CI-Workflow-001: Required check + path filter anti-pattern (95%) - Skill-CI-Workflow-002a: Zero SHA handling in git diff (95%) - Skill-CI-Workflow-002b: Missing commit handling with cat-file (93%) - Skill-CI-Workflow-002c: Git diff exit code validation (92%) - Skill-CI-Workflow-003: Required check deployment testing (90%) - Skill-Architecture-016: ADR compliance documentation (88%) - Skill-Implementation-007: Fast iteration cycle pattern (92%) **Key Learnings**: - Path filters on required check workflows cause phantom blocking - Internal skip logic preserves efficiency while ensuring status reports - Git diff in workflows needs comprehensive edge case handling - Fast iteration (<10min cycles) enabled 5 rounds in 20 minutes **Memory Files Created**: - ci-workflow-required-checks.md (5 skills) - architecture-adr-compliance-documentation.md (1 skill) - implementation-fast-iteration.md (1 skill) **Related**: PR #342 (merged), PR #343 (pending merge) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs(session): update session log with commit SHA --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
5f1e500
Session Protocol Compliance ReportTip ✅ Overall Verdict: PASS All session protocol requirements satisfied. What is Session Protocol?Session logs document agent work sessions and must comply with RFC 2119 requirements:
See .agents/SESSION-PROTOCOL.md for full specification. Compliance Summary
Detailed Results2025-12-24-session-85-pr-342-343-retrospectiveBased on my analysis of the session log: Run Details
Powered by AI Session Protocol Validator - View Workflow |
AI Quality Gate ReviewCaution ❌ Final Verdict: CRITICAL_FAIL WalkthroughThis PR was reviewed by six AI agents in parallel, analyzing different aspects of the changes:
Review Summary
Analyst Review DetailsLet me check the local repository for changes and memory files. Now I have enough context to provide a thorough analysis. Analyst PR Review: Serena Memories for GitHub Workflow ProtocolsCode Quality Score
Overall: 5/5 Impact Assessment
Findings
Detailed Analysis1. File Content Review
2. Cross-Reference Verification The PR template at 3. Alignment with Existing Patterns The
4. PR Description Quality The PR uses the template correctly with:
RecommendationsNone. The PR is minimal and correctly implements Serena memory persistence for two workflow conventions already documented in the project. VerdictDevOps Review DetailsBased on my review of the PR changes, here is my DevOps assessment: Pipeline Impact Assessment
CI/CD Quality Checks
Findings
Template Assessment
Automation Opportunities
Recommendations
File Content ReviewThe two new memory files contain:
Both files are plain documentation that codify existing workflow conventions for AI agent sessions. They have no CI/CD impact. Security Review DetailsSecurity Review: Serena Memories for GitHub Workflow ProtocolsFindings
Analysis SummaryFiles Reviewed:
Security Checks Performed:
RecommendationsNone required. These are documentation files that define workflow protocols for AI agents. VerdictArchitect Review DetailsNow I have sufficient context to provide the architectural review. Design Quality Assessment
Overall Design Score: 5/5 Architectural Concerns
No architectural concerns identified. The files follow established patterns documented in ADR-007 (Memory-First Architecture). Breaking Change Assessment
Technical Debt Analysis
ADR Assessment
Recommendations
VerdictQA Review DetailsVERDICT: CRITICAL_FAIL Roadmap Review DetailsLet me examine the PR changes by looking at the Serena memory files being added. Now I have sufficient context. Let me analyze this PR from a roadmap/strategic perspective. Strategic Alignment Assessment
Feature Completeness
Impact Analysis
Concerns
Recommendations
VerdictRun Details
Powered by AI Quality Gate - View Workflow |
|
Enhancement request for workflow memories: When you're working on this PR, consider adding memories that capture these two operational patterns from today's session: 1. Failed Run Investigation PatternPattern: gh-run-failure-investigation
Trigger: CI workflow failure notification
Steps:
1. gh run view <id> --log-failed # Get failure context
2. gh run view <id> --json conclusion,event,headBranch,jobs # Metadata
3. Perform RCA on root cause
4. Create issue with remediation plan (like Issue #348)2. Notification Filtering for Actionable ItemsPattern: gh-notify-actionable-filters
Command: gh notify -s -f reason=<type>
Types:
- ci_activity: Failed workflows needing investigation
- mention: Direct @mentions requiring response
- assign: New assignments to triage
- review_requested: Pending review requests
- comment: Comment threads needing replyThese patterns extend beyond PR-centric monitoring to cover the full scope of GitHub notifications that an autonomous agent should handle. Reference: Issue #348 (created from today's |
Add POSIX-compliant trailing newlines to both memory files. Addresses PR review comments from @Copilot and @rjmurillo - Add trailing newline to github-issue-assignment.md - Add trailing newline to pr-template-requirement.md Comment-IDs: 2645011918, 2645011926
Pull Request
Summary
Add Serena memory files to ensure consistent GitHub workflow behavior across AI agent sessions.
Specification References
Changes
.serena/memories/github-issue-assignment.md).serena/memories/pr-template-requirement.md)Type of Change
Testing
Agent Review
Security Review
Other Agent Reviews
Checklist
Related Issues
Related to CLAUDE.md workflow requirements added in PR #334.