rjmurillo/project-toolkit-knowledge

Create comprehensive Architectural Decision Records (ADRs). Researches the destination directory to detect existing template conventions, gathers context, determines next ADR number, generates the ADR, validates completeness, and saves. Supports multiple ADR formats (MADR, Nygard, Alexandrian, project canonical). Use when documenting technical decisions, creating new ADR files, or capturing rationale so future readers can revisit a choice. Use when you say "write an ADR", "document this decision", "document these design choices", "record why we chose this", "capture the rationale", or "for future maintainers", or when creating an ADR-like markdown file under docs/decisions/, docs/adr/, docs/architecture/, architecture/decisions/, or .project-toolkit/architecture/. Do NOT use to debate or review an existing ADR (use adr-review).

Identify code ownership before modifying validators or linters. Checks file headers for provenance indicators, reviews documentation, and determines provenance as UPSTREAM, LOCAL, VENDOR, or UNKNOWN. Prevents accidental modification of upstream tools.

Route any request to the right skill, command, or agent chain with defaults, so nobody hand-picks from the full catalog. Use when you say /autoplan, do it, handle it, figure this out, or when a concrete request names no skill. Do NOT use when the user names a specific skill or lifecycle command; invoke that directly.

Detect and stop manufactured work after a deliverable appears done, and classify a post-completion finding into the four contract classes builder-ethos.md delegates here. Use when a worker has produced a plan, issue, PR, backlog item, research artifact, or follow-up task and you need to verify it was demanded by a real user, acceptance criterion, or blocked decision instead of reward-seeking activity.

Route a founder problem to the right business framework, then load that framework on demand. Distills 14 business books (customer discovery, positioning, pricing, sales, growth, persuasion) into scored, decision-tree skills. Use when you say diagnose my business problem, what framework applies, how do I validate demand, price this, position this, generate leads, or close deals. Do NOT use for software design (use the engineering rules) or for a single named decision (use decision-critic).

Strategic framework for evaluating build, buy, partner, or defer decisions with four-phase process, tiered TCO analysis, and integration with decision quality tools. Use for strategic build/buy/partner/defer with TCO. Do NOT use for "is there an existing library for this" (use programming-advisor).

Write a timestamped, secret-redacted snapshot of decisions, progress and next actions to the checkpoints directory, then link it from the active session log. Use when you say checkpoint this, save a recovery point, or snapshot where we are before a risky change or at the end of a working block. Do NOT use to commit or push (it never does either), and do NOT use to write a retrospective (use retro).

Investigate historical context of existing code, patterns, or constraints before proposing changes. Automates git archaeology, PR/ADR search, and dependency analysis to prevent removing structures without understanding their purpose. Use when you ask "why does this code/constraint exist", "is it safe to remove this". Do NOT use for forward-risk analysis (use pre-mortem).

Scaffold project documentation (README, ARCHITECTURE, API, CODE_COMMENTS) from templates with documented standards. Use when bootstrapping docs for a new or under-documented codebase.

Gather comprehensive context from Serena memory, Context7 docs, DeepWiki, and web sources before planning or implementation. Searches across all knowledge tiers and returns a focused summary ending in a CONTEXT_LOADED marker that this skill scans to skip a repeat fetch in the same conversation. Use when you say "gather context before planning", "what do we know before I start". Do NOT use for compressing or placing skill text (use context-optimizer).

Check the Serena and Context7 plugin prerequisites and report what is missing, with the install command for each. Use when you say set up context hub, check my plugin prerequisites, or troubleshoot MCP connectivity. Do NOT use to actually gather context for a task (use context-gather), and do NOT use to search memory (use memory-search).

Analyze skill content for optimal placement (Skill vs Passive Context vs Hybrid), compress markdown to pipe-delimited format, and validate compliance against the decision framework. Passive context wins for what the model cannot know (post-cutoff APIs, repo gotchas); pre-trained knowledge belongs in progressive disclosure. Use for "analyze skill placement", "compress markdown", "optimize context", "extract and index", or "audit always-on rules". Do NOT use for gathering knowledge before a task (use context-gather) or for creating or improving a skill (use skillforge).

Maintain Serena memory files in place. Mark superseded content, keep current truth visible inline, and run the supersession sweep that proposes a disposition per file without editing it. Use when you say "how do I mark a memory obsolete", "how do I supersede a memory", or "run the supersession sweep". Do NOT use for merging or deleting Serena files or tidying Serena indexes; use memory-consolidate.

Classify problems into Cynefin Framework domains (Clear, Complicated, Complex, Chaotic, Confusion) and recommend appropriate response strategies. Use when unsure how to approach a problem, facing analysis paralysis, or needing to choose between expert analysis and experimentation.

Structured decision critic that systematically stress-tests reasoning before commitment surfacing hidden assumptions verifying claims and generating adversarial perspectives to improve decision quality. Do NOT use to surface failure risks pre-launch (use pre-mortem), probe why a constraint exists (use chestertons-fence), or ask the user to choose (use decision-question).

Ask the user to choose only when blocked on a decision they own, with the smallest complete decision brief. Use when you say ask the user to choose, do I need a user decision here, or present a decision brief. Do NOT use to review a decision already made (use decision-critic) or to surface project risks (use pre-mortem).

Design an API, schema, or module boundary from the business behavior it must support, not from source payload shape or generic CRUD. Decides explicit state, domain operation versus CRUD, and history, then checks the design against use cases. Use when you say design this schema, API design, or CRUD or domain operation. Do NOT use for abstraction discovery (use cva-analysis).

Decide whether evidence is independent or the same loop twice, and whether a named check was run. Classifies lineage (premise, origin, time, mutability, environment), keeps authority a separate axis, and reports VERIFIED, NOT RUN, UNAVAILABLE, or FAILED. Use when you say is this independent evidence, did the reviewer confirm this, closed loop, or count the confirmations. Do NOT use to report progress (use the voice rule) or to pick the governing validator (use validation-authority).

Thin router for the tiered memory system. Points callers at the focused sub-skills for each operation, Tier 1 search, the reflexion write path, the memory-first gate, maintenance, and consolidation. Use when you ask "what do we know about X", "recall prior context", or "search memory" and are not sure which operation you need. Do NOT use for adding citations (use memory-enhancement) or narrative cross-system reports (use memory-documentary).

Reflective consolidation pass over Serena memory files. Separates durable context (preferences, working style, key relationships, recurring workflows) from dated context (projects, deadlines, one-off tasks), merges duplicate topic files onto the richer path, converts relative dates to absolute ones, and tidies memory-index.md so a future session orients fast without re-asking. Use when you say consolidate memory, consolidate Serena memory, merge memory files, or tidy the memory index. Do NOT use for in-file supersession markers (use curating-memories) or health, token, or size checks (use memory-maintenance).

Generate evidence-based documentary reports by searching across all 3 memory systems (Claude-Mem, Serena, DeepWiki), .agents/ artifacts, and GitHub issues. Produces investigative journalism-style analysis with full citation chains. Use when you ask for an "evidence-based report", "investigate across all memory systems", "what happened with X over time". Do NOT use for a single semantic recall (use memory) or for citation hygiene (use memory-enhancement).

Manage memory citations, verify code references, and track confidence scores. Use when adding citations to memories, checking memory health, or verifying code references are still valid. Use when you say "add a citation", "verify this memory's code refs", "check memory health". Do NOT use for searching or creating memories (use memory) or for documentary reports (use memory-documentary).

Deal intelligence skill for offer analysis and counter-proposal drafting. Trigger on review this offer, analyze counter, value gap, draft counter, should I walk. Apply when reviewing any offer (real estate, compensation, vendor, resource allocation) or designing negotiation analysis behavior in agentic systems. Quantifies value gaps and applies the RADAR protocol.

Triage raw unstructured input (transcripts, brain dumps) into evaluated thread inventories and a synthesized gold-found file. Four phases: front-gate, extract, evaluate, synthesize. Use when you say "pan for gold", "triage transcript", "synthesize gold-found", or hand it a voice transcript or brain dump. Do NOT use for structured input like specs or ADRs (use analyst or spec-generator instead).

Guide prospective hindsight analysis to identify project risks before failure occurs. Teams imagine the project has failed spectacularly, then work backward to identify causes. Increases risk identification by 30% compared to traditional planning. Use when you say "run a pre-mortem on", "what could cause this to fail", "identify project risks", or "what could go wrong with". Do NOT use to stress-test a single decision's reasoning (use decision-critic).

Evaluate existing solutions (libraries, SaaS, open source) AND internal prior-art before custom development to avoid reinventing the wheel. Use when considering building new features, asking "should I build or use existing", "do we already have this", "is there existing code for X in this repo", "is there a library for this", or need build vs buy cost analysis with token estimates. Checks internal reuse (leverage/extend) before external. Do NOT use for strategic multi-option TCO (use buy-vs-build-framework).

Optimize system prompts for Claude Code agents using proven prompt engineering patterns. Use when users request prompt improvement, optimization, or refinement for agent workflows, tool instructions, or system behaviors. Use when you say "optimize this prompt", "improve this system prompt", or "review my agent prompt".

Pre-emit AI-vernacular self-check an agent runs on its OWN prose before writing a session-log narrative, ADR context section, retrospective, or PR description. Four layers ordered by reader-trust, not ease of detection. Use when you say prose self-check, audit my writing for AI tells, does this read as AI-written, or before emitting any prose artifact. Do NOT use for code style (use style-enforcement) or to rewrite human-authored text.

CRITICAL learning capture. Extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes and preserve what works. Use PROACTIVELY after user corrections ("no", "wrong"), after praise ("perfect", "exactly"), when discovering edge cases, or when skills are heavily used. Without reflection, valuable learnings are LOST forever. Acts as continuous improvement engine for all skills. Invoke EARLY and OFTEN - every correction is a learning opportunity.

Adversarial requirements interview that walks the design tree to elicit testable requirements before any code is written (the grill-me pattern), or audits an existing multi-section spec for ambiguity with source-anchored questions. Skip any question the codebase can already answer. Use when you say "interview me on this", "grill me on the requirements", "walk the design tree", or "audit this spec for ambiguity".

Fill an unfilled auto-retrospective skeleton for a date, or list the skeletons still pending. Use when you say retro fill, fill retro skeleton, or list pending retros. Do NOT use to run the retrospective analysis itself (this hands off to the retrospective skill), and do NOT use to write a session log.

Extract learnings from a session or task through structured retrospective frameworks. Gathers evidence, runs Five Whys and fishbone diagnosis, scores atomicity, and writes a canonical retrospective artifact. Use to turn execution experience into institutional knowledge. Use when you say "run a retrospective", "retro fill", or "extract learnings from this session". Do NOT use for in-conversation correction capture (use the reflect skill).

Build a small set of project-specific workflow skills from verified repository, tracker, session, and memory evidence. Use when you say bootstrap skills, capture project workflow knowledge, build this repo's skill library, or project skill library. Reuses existing skills first, then runs skillforge, context-optimizer, and skillopt in order. Do NOT use for one skill (use skillforge) or for scored tuning (use skillopt).

Intelligent skill router and creator. Analyzes ANY input to recommend existing skills, improve them, or create new ones. Uses deep iterative analysis with 11 thinking models, regression questioning, evolution lens, and multi-agent synthesis panel. Phase 0 triage ensures you never duplicate existing functionality. Use when you say "create a skill", "do I have a skill for", "which skill should I use", "improve the X skill", or "SkillForge: {goal}". Do NOT use for context optimization, placement analysis, markdown compression, extraction and indexing, or rule audits (use context-optimizer), eval-gated optimization of an existing skill (use skillopt), or saving finished work as a skill (use skillify).

Extract a reusable skill from a workflow you just finished. Use when you say skillify this, save this as a skill, or make this proper. Do NOT use to design a skill from a goal (use skillforge).

Improve a skill, agent file, or prompt through bounded patches and a held-out, per-task acceptance gate. Use when you say optimize this skill, make this skill better, compress these skills safely, tune this prompt against an eval, or a skill keeps failing the same way. Refuses unscored improvement claims. Do NOT use to create or route skills (use skillforge) or to decide skill placement or compress markdown without an eval (use context-optimizer).

Route design and code-risk tasks to engineering references. Use for architecture boundaries, interfaces, domain modeling, refactoring, and legacy tests. Also cover data consistency, resilience, and forbidden patterns. Route prior-art questions to programming-advisor. Route scoring to code-qualities-assessment, and CVA to cva-analysis.

Turn a problem into testable requirements with acceptance criteria, through a first-principles gate, a memory-first prior-art gate, and a PRD schema. Use when you say spec this out, what should we build, or define the requirements, and run it before plan. Do NOT use to sequence work into milestones (use plan), do NOT use to write the code (use build), and do NOT use to emit the REQ, DESIGN and TASK files directly (use spec-generator, which this invokes).

Guidance for using Serena's LSP-powered symbol analysis. Use when you say "how do I find a symbol", "trace references for this method", "explore this file's structure", or when grep/text search would be imprecise. Do NOT use for memory guidance (use memory).

Run a 5-layer interview to elicit how a team actually works (rhythms, decisions, dependencies, institutional knowledge, friction) and emit a structured operating model. Use when you say "elicit operating model", "interview team operating model", "how does this team actually work", or "validate operating model". Do NOT use for code analysis (use the analyst agent), external audience narratives (use the explainer agent), or retrospectives (use the retrospective agent).

Twenty-minute diagnostic mapping a team to a world-model paradigm (vector DB, structured ontology, signal-fidelity). Use when you say "run the world model diagnostic", "audit our world model", "which world model architecture fits us", or "audit where we automate judgment". Use for AI readiness assessments and boundary-layer audits where automated judgment is safe. Do NOT use for mapping team operating rhythms or decision flows; use work-operating-model instead.