session-review: add plugin-improvement lens for plugin-misbehavior signal#80
Merged
Merged
Conversation
…gnal (closes #75) Adds a third lens to session-review's Step 1 alongside the existing technical (vault) and collaboration (memory) lenses. The plugin- improvement lens scans for moments where an agent or skill shipped under plugins/athena-notes/ misbehaved or has a sharp edge worth filing, runs them through the Signal Test with issue-route tunings in Step 1.5, surfaces survivors as GitHub-issue drafts at Step 5, and on approval invokes /issue-create with the draft body as seed text. Two gates total: this skill's Step 5 catches "is this worth filing?", /issue-create's Stage 3.4 catches "is the post correct?". The seed's default-structure headings (Problem / Proposed behavior / Scope / Acceptance / Open questions) cover /issue-create's Stage 2 areas, so most Q&A skips per its existing "skip if already answered" rule. Strictly scoped: only plugins/athena-notes/ agents and skills. Cross-plugin gripes continue to flow through the collaboration lens to memory; generic engineering tech-debt is engineering:tech-debt's territory, not this skill's. Mirrors the structural shape of PR #56 (the collaboration-lens precedent the issue body cites): same lens-definition addition, Signal Test extension, categorization-table row, output template, handoff step, edge-case + guardrail update, plus the same one-line AGENTS.md scope-note extension and CHANGELOG bullet.
- Add ## Implementation hints section to GitHub-issue draft template and update Step 10's skip-rationale list to include it (Stage 2.4 was being silently re-asked because the seed didn't cover that area). - Q1 dedup gains keyword-hygiene guidance: pass --search as a separate arg token, strip shell metacharacters from candidate-derived keywords, cap query length at ~200 chars to avoid the GitHub Search API per-qualifier limit silently returning zero matches. - Clarify the Open questions placeholder as drop-the-section-if-empty rather than leaving a placeholder bullet that would re-trigger /issue-create Stage 3.3. - Add a cwd-mismatch caveat to Step 10: the "Filing this against ..." lead-in is a hint, not an override; /issue-create Stage 1.1 resolves the target from origin and will ask if cwd's origin differs.
…, soften cwd caveat - Step 1 collaboration-lens bullet now points at Step 1.5's cross-lens routing exception, so a reader of Step 1 alone doesn't conclude collaboration signal can never land on issue-routes. - Signal Test Q1 gains a parenthetical pointing at Step 1.5 Q1's open-issue-list dedup for issue-route candidates. - Q1 keyword-hygiene rule swaps the enumerative strip list (`"`, `;`, `$`, backticks) for a positive allowlist (alphanumeric / hyphen / underscore / whitespace) so it doesn't go stale on the next shell metacharacter someone thinks of. - Step 10 cwd-mismatch caveat softens "will detect" to a behavior conditional on Stage 1.1's "user's initial message" branch firing on the seed lead-in, with a fallback to manual call-out at /issue- create's Stage 3.4 gate.
…e duplicate - Q1's tuning bullet replaces the placeholder `<keywords>` with a concrete example string so an LLM running the skill pattern-matches on the safe form rather than the placeholder. - Keyword-hygiene rule moves from inline-on-Q1 to a callout after the four questions, restoring the Q1–Q4 one-sentence parallel structure while keeping the rule reachable from Q1 via a forward reference. - Categorization Criteria scoping note drops the plugin-improvement scope sentence — it duplicated Step 1's lens definition. The scoping note now points at Step 1 for the rule rather than restating it.
…caveats - /issue-create has no Stage 2.4 — Implementation hints is area 4 inside Stage 2.1. Update the GitHub-issue draft template's Implementation hints placeholder to reference the actual section. - Signal Test Q2 prose now lists three destinations rather than two (Vault / Harness memory / GitHub issue against this repo) so a reader of Q2 in isolation doesn't drop a valid issue-route candidate before reaching Step 1.5's tunings. - Step 10's cwd-mismatch note rolls into a single Caveats block: the target-repo verification is unconditional at Stage 3.4 (Stage 1.1's detection is hint-dependent), and a sibling reminder to re-read the rendered draft for anything session-derived that shouldn't appear in a public issue. - Trim Q1 dedup cross-references at the Signal Test preamble and Step 2 item 4 to bare forward-references; the inline procedure belongs once at Step 1.5 Q1. - Drop the parenthetical from the Categorization Criteria scoping blockquote; it was addressing a non-concern. - Replace "cross-lens routing rule" with "destination-row routing" in the collaboration-lens bullet so the cross-reference matches the phrase used at Step 1.5. - Tighten the Q1 keyword-hygiene rationale: GitHub Search's limit is total query length, not per-qualifier.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a third lens to
session-review's Step 1 alongside the existing technical (vault) and collaboration (memory) lenses. The new plugin-improvement lens scans for moments where an Athena Notes agent or skill misbehaved or has a clear sharp edge worth filing, runs them through the Signal Test with issue-route tunings, surfaces survivors as drafts at the Step 5 approval gate, and on approval invokes/issue-createwith the draft body as seed text. Two gates total: this skill's Step 5 catches "is this worth filing?",/issue-create's Stage 3.4 catches "is the post correct?".Strictly scoped — only
plugins/athena-notes/agents and skills. Cross-plugin gripes continue routing through the collaboration lens to memory; generic engineering tech-debt isengineering:tech-debt's territory.Mirrors the structural shape of #56 (the collaboration-lens precedent #75 cites): Step 1 lens addition, Signal Test extension, categorization-table row, output template, handoff step, edge-case + guardrail updates, plus the same one-line
AGENTS.mdscope-note extension andCHANGELOGbullet.Closes #75.
Test plan
python3 scripts/lint-frontmatter.py plugins/athena-notes/skills/session-review/SKILL.mdpasses (skill body is LLM instructions; no test suite touchessession-review)./issue-createStage 1.3's six default-structure headings exactly (Problem / Motivation, Proposed behavior, Scope (in/out), Implementation hints, Acceptance criteria, Open questions) so Stage 2.1's "skip if already answered" fires on each area.correctness/security/simplicitylenses; 15 findings accepted across passes, 7 push-backs, 3 skips. Audit at~/.claude/issue-work/SnowboardTechie-athena-notes-75/summary.md.Changelog
## [Unreleased]inCHANGELOG.md.