commit a91a875f01b46a50b180942051e09a225307e45e Author: Zhongwei Li Date: Sun Nov 30 09:02:04 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..4f77683 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "steerings-generator", + "description": "Extract tacit engineering knowledge through guided interviews and generate structured steerings", + "version": "1.0.1", + "author": { + "name": "Timur Khakhalev", + "email": "timur.khakhalev@gmail.com" + }, + "skills": [ + "./skills" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..cd55bee --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# steerings-generator + +Extract tacit engineering knowledge through guided interviews and generate structured steerings diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..48cbf94 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,57 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:timurkhakhalev/cc-plugins:steerings-generator-cc-skill", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "c736806519ae68a3f38620a2152a3c88e59006e6", + "treeHash": "bf979c57cc8af25a7342d98df9a867f6fd887f28850dcd7e9eeea588890ac9cc", + "generatedAt": "2025-11-28T10:28:41.546775Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "steerings-generator", + "description": "Extract tacit engineering knowledge through guided interviews and generate structured steerings", + "version": "1.0.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "742feb10882b964e3f3b593882ec1ca6a6aa934008b13d73efbc425c792e903b" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "2b9c56386901c4ab2a60a3cab2e642821977eb0522b216389efdaf424ef6aa6b" + }, + { + "path": "skills/steerings-generator/pack-reference.md", + "sha256": "9e3fbcce2dfc6fae54a8da379095d1e598af535ae89435973f7f28146deb399b" + }, + { + "path": "skills/steerings-generator/interview-packs.md", + "sha256": "74c6b4cfdb9119a7649afff2d4c209635e6673a70327a02fd06062fc8b282136" + }, + { + "path": "skills/steerings-generator/steering-template.md", + "sha256": "d1717795a95e4446e420b0f6c14627dd8aeef34ff3e8b203345000aeeab6c10f" + }, + { + "path": "skills/steerings-generator/SKILL.md", + "sha256": "c7da1024ee5485b23df5c6784c1ed1d6f1ef6659c84faece170b75552b31d5a3" + } + ], + "dirSha256": "bf979c57cc8af25a7342d98df9a867f6fd887f28850dcd7e9eeea588890ac9cc" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/steerings-generator/SKILL.md b/skills/steerings-generator/SKILL.md new file mode 100644 index 0000000..1c73328 --- /dev/null +++ b/skills/steerings-generator/SKILL.md @@ -0,0 +1,1288 @@ +--- +name: steerings-generator +description: Extract tacit engineering knowledge through guided interviews and generate structured steerings. Use when user mentions "steerings", "tacit knowledge", "conventions", "engineering practices", "interview", or wants to document team/project knowledge. Also activates when user asks for "steerings for X", "document X conventions", or wants to extract knowledge about a specific topic. Supports reviewing and transforming existing steerings to standard format. +allowed-tools: Read, Write, AskUserQuestion, Glob, Task +--- + +# Steerings Generator + +This skill conducts context-aware interviews to extract tacit engineering knowledge and generate agent-readable steerings. It analyzes the current codebase to ground questions in reality, while also asking about planned conventions and future intentions. Produces concise steerings in the format: **Intent (Why) → Rules (What) → Practices (How) → Meta**. + +Supports both **predefined knowledge packs** (8 common areas like architecture, testing, security) and **custom topics** (user-specified areas like "GraphQL conventions", "Terraform patterns", "mobile development"). + +**Agent Consumption:** Generated steerings are placed in the configured steerings directory (default: `steerings/`) for AI coding agents to read. This is the canonical location. If using `.memory-bank/steerings/`, that is a separate persistence layer - agents should read from the configured `steeringsPath`. + +## When to Use This Skill + +Activate when the user wants to: + +- Extract and document tacit engineering knowledge +- Create steerings for AI coding agents +- Document conventions, architecture decisions, or team practices +- Generate structured documentation from implicit knowledge +- Define standards for new or existing projects +- Document conventions for a specific technology or domain (custom topics) +- Review and transform existing steering files into standard format + +## Prerequisites + +- Interview pack guidance in `.claude/skills/tacit-knowledge/pack-reference.md` (defines topic areas and questions) +- Write access to create `steerings/` and `sessions/` directories +- Access to AskUserQuestion and Task tools + +## Mode Selection + +**Check if user wants to review/transform existing steerings:** + +Detect keywords: "review steerings", "transform steerings", "convert steerings", "fix steerings format" + +**If reviewing existing steerings:** + +- Skip to **Review Mode** (Step R) +- Do NOT run interview flow + +**Otherwise:** + +- Continue with **Interview Flow** (Step 0) + +## Interview Flow + +### Step 0: Configure Output Paths + +**Before starting the interview, determine where to save outputs:** + +1. **Auto-detect existing folders:** + - Check if `steerings/` exists in current working directory + - Check if `sessions/` exists in current working directory + +2. **Ask user to confirm or customize paths** using AskUserQuestion: + +```yaml +questions: + - question: "Where should generated steering files be saved?" + header: "Steerings" + multiSelect: false + options: + - label: "./steerings/" + description: "Default location (will be created if doesn't exist)" + - label: "docs/steerings/" + description: "Inside docs/ folder" + - label: ".steerings/" + description: "Hidden folder in project root" + - label: "Custom path" + description: "Specify a custom directory path" + + - question: "Where should interview session files be saved?" + header: "Sessions" + multiSelect: false + options: + - label: "./sessions/" + description: "Default location (will be created if doesn't exist)" + - label: ".sessions/" + description: "Hidden folder in project root" + - label: "docs/sessions/" + description: "Inside docs/ folder" + - label: "Custom path" + description: "Specify a custom directory path" +``` + +3. **Handle custom paths:** + - If user selects "Custom path", they'll provide path via text input + - Validate path is relative (not absolute) + - Normalize "./" to current directory + - Reject standalone "." (ambiguous) + - Trim leading/trailing whitespace + - Ensure path ends with "/" (add if missing, e.g., "my-docs/steerings" → "my-docs/steerings/") + - Reject paths containing filenames (must be directory only) + +4. **Store paths for use throughout the flow:** + - `steeringsPath` (e.g., `"steerings/"`, `"docs/steerings/"`, `".steerings/"`) + - `sessionsPath` (e.g., `"sessions/"`, `".sessions/"`, `"docs/sessions/"`) + +5. **Create both directories immediately after confirmation if they don't exist** + +6. **Preflight validation after directory creation:** + - Check write permissions to both directories (attempt to create a test file `.write-test` and delete it) + - Check for potential filename collisions if regenerating: + - For predefined packs: Check if concise filenames (code-ownership.md, architecture-invariants.md, etc.) already exist + - For custom topics: Check if `{packId}.md` already exists + - Warn user if collisions detected, ask whether to overwrite or cancel + - Check if `index.md` exists and warn if it will be regenerated + +**Default values if skipped:** + +- `steeringsPath = "steerings/"` +- `sessionsPath = "sessions/"` + +### Step 1: Define Topics (Predefined Packs or Custom Topics) + +**Detect if user specified a custom topic:** + +- Check user's initial request for patterns: "steerings for X", "document X conventions", "extract knowledge about X" +- Extract topic name X from request +- Examples: "GraphQL API patterns", "Terraform modules", "mobile development", "React hooks" + +**If custom topic detected:** + +Check if topic is sufficiently clear. A clear topic has: + +- Specific technology/domain mentioned +- Reasonable scope (not too broad like "everything" or "all frontend") + +**If topic is unclear or too broad, use AskUserQuestion to clarify scope:** + +```yaml +questions: + - question: "What aspects of {topic} do you want to document?" + header: "Aspects" + multiSelect: true + options: + - label: "Code patterns and structure" + description: "File organization, naming conventions, module structure" + - label: "Architecture and design" + description: "System design, component relationships, data flow" + - label: "Development process" + description: "Workflow, tooling, build/deploy process" + - label: "Quality and testing" + description: "Test patterns, quality standards, verification approach" + - label: "Security and compliance" + description: "Auth patterns, data handling, security practices" + + - question: "What level of detail should the conventions cover?" + header: "Level" + multiSelect: false + options: + - label: "File and module patterns" + description: "How individual files and modules should be organized" + - label: "System-level design" + description: "How major components interact and depend on each other" + - label: "Team workflows" + description: "How team members collaborate and deliver changes" + + - question: "What's the scope of {topic}?" + header: "Scope" + multiSelect: false + options: + - label: "Specific library/framework" + description: "Conventions for using a particular tool or library" + - label: "General domain area" + description: "Broader conventions across a technology domain" + - label: "Cross-cutting concern" + description: "Patterns that apply across the entire stack" +``` + +Generate topic definition: + +- **packId**: kebab-case from topic name (e.g., "graphql-api-patterns") +- **packName**: Human-readable name (e.g., "GraphQL API Patterns") +- **packType**: "custom" +- **customTopicDescription**: Synthesize from clarification answers (1-2 sentences) + +**If NO custom topic detected:** + +Present all 8 available predefined knowledge packs in a single multi-select question: + +```yaml +questions: + - question: "Which knowledge areas do you want to document? (Select all that apply)" + header: "Packs" + multiSelect: true + options: + - label: "Codebase Topology & Ownership" + description: "Document module boundaries, ownership, shared code patterns" + - label: "Architecture & Design Invariants" + description: "Document layering, dependencies, design patterns" + - label: "Business Domain Contracts" + description: "Document domain entities, business rules, compliance" + - label: "Quality & Style Assurance" + description: "Document code quality, Definition of Done, standards" + - label: "Testing & Verification Strategy" + description: "Document test types, coverage, structure" + - label: "Risk & Historical Landmines" + description: "Document dangerous areas, past failures, workarounds" + - label: "Security, Data & Compliance" + description: "Document auth, secrets, PII/PHI, security patterns" + - label: "Delivery Lifecycle & Change Flow" + description: "Document branching, PRs, deployment, configuration" +``` + +Map selected pack labels to pack IDs: + +- "Codebase Topology & Ownership" → `codebase-topology-ownership` +- "Architecture & Design Invariants" → `architecture-design-invariants` +- "Business Domain Contracts" → `business-domain-contracts` +- "Quality & Style Assurance" → `quality-style-assurance` +- "Testing & Verification Strategy" → `testing-verification-strategy` +- "Risk & Historical Landmines" → `risk-historical-landmines` +- "Security, Data & Compliance" → `security-data-compliance` +- "Delivery Lifecycle & Change Flow" → `delivery-lifecycle-change-flow` + +**Result:** List of topics to process (mix of predefined packs and/or custom topics), each with: + +- `packId` (string) +- `packName` (string) +- `packType` ("predefined" | "custom") +- `customTopicDescription` (string, custom only) +- `explorationScope` (object with clarification answers, custom only) + +Proceed to Step 2 with all selected topics. + +### Step 2: Discover Existing Documentation & Conventions + +**Run TWO Explore agents independently (both must complete before Step 3)** (before processing individual packs): + +**Explore #1 - Documentation & Conventions:** + +```yaml +subagent_type: "Explore" +description: "Find docs and conventions" +prompt: | + Analyze this repository with medium thoroughness to find existing documentation and conventions: + + - Steering files (steerings/, .steerings/, docs/steerings/) + - Development conventions (CONVENTIONS.md, DEVELOPMENT.md, CONTRIBUTING.md) + - Architecture docs (ARCHITECTURE.md, docs/architecture/) + - Code style guides (STYLE.md, .styleguide) + - Agent instructions (CLAUDE.md, .claude/CLAUDE.md, .aider/, .cursor/) + - README sections on conventions, patterns, standards + - Package.json scripts showing development workflow + - Config files with conventions (eslint, prettier, tsconfig) + + Report concrete findings with file paths. Focus on conventions, rules, and standards that affect how code should be written. +``` + +**Explore #2 - General Repository Context:** + +```yaml +subagent_type: "Explore" +description: "Understand repo structure" +prompt: | + Analyze this repository with medium thoroughness to understand: + + - Project purpose and domain + - Tech stack and key dependencies + - Directory structure and organization + - Main modules and their responsibilities + - Notable patterns or frameworks used + + Report high-level findings to provide context for interview questions. +``` + +**Usage of Findings:** + +- Use docs findings to inform question generation (reference existing conventions) +- Ask clarifying questions during interview if docs are unclear or incomplete +- Incorporate documented conventions into generated steerings +- Reference repo context to make questions more specific and relevant +- **If no existing documentation found:** Proceed with topic guidance + generic repo structure from Step 2 Explore #2 +- **Note:** These are global findings; Step 4 will discover topic-specific patterns without re-scanning general structure + +**Caching for reuse:** + +- Cache Step 2 findings for use in Step 4 and Step 7 +- Pass as context to avoid re-scanning general repository structure +- Step 4 should focus only on topic-specific patterns, referencing Step 2 for general context + +**Proceed to Step 3 after both Explore agents complete.** + +### Step 3: Process Each Topic Sequentially + +**IMPORTANT**: Process ONE topic at a time (whether predefined pack or custom topic) through all steps before moving to the next: + +1. Analyze current topic with Explore (Step 4) +2. Generate questions for current topic (Step 5) +3. Conduct interview for current topic (Step 6) +4. Save current topic responses to session +5. Move to next topic and repeat Steps 4-6 + +DO NOT analyze all topics first and then generate all questions. Process sequentially. + +The processing flow is the same for both predefined packs and custom topics, with differences in: + +- **Step 4**: Predefined uses template Explore prompts, custom generates dynamic prompts +- **Step 5**: Custom topics use flexible question count (3-7 based on scope) + +### Step 4: Analyze Topic-Specific Codebase Context + +For the current topic being processed, **use Task tool with subagent_type=Explore** to discover existing patterns. + +**Important:** + +- Use thoroughness level "medium" for balanced exploration +- Explore finds what currently exists +- Questions will also cover planned/future conventions (not just what exists) +- Only analyze the current topic, not all topics at once +- **Note:** Focus only on topic-specific patterns; reference Step 2 for general structure +- **Reuse Step 2 cache:** Include Step 2 findings (docs/conventions + repo context) in Explore prompts to avoid re-scanning. Focus only on discovering new topic-specific patterns. + +**Check packType to determine exploration approach:** + +**For CUSTOM TOPICS (`packType: "custom"`):** + +Generate dynamic Explore prompt from `customTopicDescription` and `explorationScope`: + +``` +Analyze this codebase with medium thoroughness for {topic}: + +Topic: {customTopicDescription} + +Focus areas based on user's scope: +{List aspects selected in clarification, e.g.:} +- Code patterns and structure +- Architecture and design +- Quality and testing + +Look for: +- Files, directories, and modules related to {topic} +- Configuration files for {topic} +- Usage patterns and conventions +- Integration points with other systems +- Tests related to {topic} +- Documentation mentioning {topic} + +Report concrete findings with file paths and code examples. +``` + +**For PREDEFINED PACKS (`packType: "predefined"`):** + +Use template Explore prompts below based on packId. + +**Explore Prompts by Predefined Pack:** + +**Pack 1 - Codebase Topology & Ownership:** + +``` +Analyze this codebase with medium thoroughness to find: +- Shared code organization (shared/, common/, utils/, lib/ folders) +- Module boundary patterns (feature folders, domain folders, layers) +- Ownership markers (CODEOWNERS, README ownership sections) +- Directory structure conventions +- Import patterns and path aliases +- Workspace dependencies if monorepo + +Report concrete findings with file paths and examples. +``` + +**Pack 2 - Architecture & Design Invariants:** + +``` +Analyze this codebase with medium thoroughness to find: +- Layering patterns (controllers, services, repositories, handlers) +- Dependency directions between layers +- Import conventions (relative vs path aliases) +- Event systems (EventEmitter, domain events, message buses) +- Design patterns (decorators, DTOs, factories) +- Performance patterns (caching, lazy loading) +- API conventions (REST, GraphQL, gRPC endpoints) + +Report concrete findings with file paths and code examples. +``` + +**Pack 3 - Business Domain Contracts:** + +``` +Analyze this codebase with medium thoroughness to find: +- Domain entity definitions and models +- Permission/role enforcement patterns +- Feature flag or licensing tier implementations +- Audit log or compliance-related code +- Money-handling or financial logic +- Domain event naming patterns + +Report concrete findings with file paths and examples. +``` + +**Pack 4 - Quality & Style Assurance:** + +``` +Analyze this codebase with medium thoroughness to find: +- Code formatting config (prettier, eslint) +- Naming conventions in actual code +- Logging and error handling patterns +- Observability instrumentation +- Quality check scripts (lint, type-check, test commands) +- PR templates or contribution guidelines + +Report concrete findings with file paths and examples. +``` + +**Pack 5 - Testing & Verification Strategy:** + +``` +Analyze this codebase with medium thoroughness to find: +- Test file locations and naming patterns +- Test types used (unit, integration, e2e) +- Testing framework config (jest, vitest, cypress) +- Coverage configuration +- Test data and fixture patterns +- Mock/stub patterns + +Report concrete findings with file paths and examples. +``` + +**Pack 6 - Risk & Historical Landmines:** + +``` +Analyze this codebase with medium thoroughness to find: +- Comments mentioning "TODO", "FIXME", "HACK", "DEPRECATED" +- Workarounds or legacy code markers +- Version-specific code or compatibility shims +- Areas with high complexity or technical debt +- Commented-out code blocks with explanations + +Report concrete findings with file paths and examples. +``` + +**Pack 7 - Security, Data & Compliance:** + +``` +Analyze this codebase with medium thoroughness to find: +- Authentication/authorization implementations +- Secret management patterns (env vars, vaults) +- Input validation and sanitization +- PII/PHI handling code +- Security-related middleware or guards +- Data access control patterns +- Encryption or hashing usage + +Report concrete findings with file paths and examples. +``` + +**Pack 8 - Delivery Lifecycle & Change Flow:** + +``` +Analyze this codebase with medium thoroughness to find: +- Git workflow files (.github/workflows, CI config) +- Branching strategy markers (branch protection, naming) +- PR templates and commit message conventions +- Deployment scripts and configuration +- Environment config patterns (.env files) +- Changelog or version management +- Release automation + +Report concrete findings with file paths and examples. +``` + +**Task Tool Usage:** + +```yaml +subagent_type: "Explore" +description: "Analyze codebase for {pack-name} patterns" +prompt: | + [Use appropriate prompt from above based on selected pack] +``` + +### Step 5: Generate Context-Aware Questions (Current Topic Only) + +**Determine question count:** + +**For PREDEFINED PACKS:** Always generate 5 questions. + +**For CUSTOM TOPICS:** Generate 3-7 questions based on topic scope: + +- **3-4 questions** if: + - Topic description < 50 chars OR + - Single aspect selected OR + - Explore findings ≤ 2 files/areas + +- **5 questions** if: (default fallback) + - Topic description 50-100 chars OR + - 2-3 aspects selected OR + - Explore findings 3-5 files/areas + +- **6-7 questions** if: + - Topic description > 100 chars OR + - 4+ aspects selected OR + - Explore findings 6+ files/areas + +**If heuristics conflict, default to 5 questions.** + +**Precise definitions:** + +- **"areas"**: Unique directories or major modules returned by Explore agent findings +- **"aspects"**: Number of multi-select items chosen in clarification questions +- **"description length"**: Character count of customTopicDescription string + +**Precedence when heuristics conflict:** + +1. Description length (highest priority) +2. Aspect count +3. Explore findings (lowest priority) +4. Tie-breaker: Default to 5 questions + +Based on **three sources**, generate questions dynamically for this topic only: + +1. Topic-specific Explore findings (Step 4) +2. Documentation/conventions findings (Step 2) +3. Pack topic guidance (from pack-reference.md for predefined, or clarification scope for custom) + +**Question Generation Guidelines:** + +1. **Ground in current reality:** Use topic-specific Explore findings + existing docs to inform questions +2. **Reference actual code and docs:** "I see you use X pattern in Y file..." or "Your CONVENTIONS.md says X, but..." +3. **Clarify unclear docs:** If existing docs are incomplete or ambiguous, ask clarifying questions +4. **Ask about conventions, not roadmap:** Focus on "how should X be done?" not "will you build X?" +5. **Incorporate existing standards:** Reference documented conventions and ask if they should apply to related areas +6. **Offer 4 options (A/B/C/D):** Present realistic choices based on common patterns + existing conventions +7. **Mark one option as recommended:** Add "⭐ Recommended" as the LAST token in the description field (after a space) for the option you think is best practice. This star must appear at the exact end of the description text. See Step 7 Validation Requirements for detailed rule style examples. +8. **Only generate questions for current topic:** Do not generate questions for other topics yet +9. **If Explore finds nothing:** Generate questions based on establishing conventions (ask "how should X be done?" for the topic) + +**Good vs Bad Questions:** + +✅ **Good (asks about conventions):** + +- "How should shared utilities be organized?" +- "Where should authentication logic live?" +- "What naming convention should API endpoints follow?" + +❌ **Bad (asks about roadmap/features):** + +- "Will you implement OAuth authentication in Q2?" +- "Are you planning to add a mobile app?" +- "What features are on the roadmap?" + +**Example Generated Questions:** + +For "Codebase Topology & Ownership" (after Explore finds `src/utils/` and `src/lib/`): + +``` +Q1: I found both `src/utils/` and `src/lib/` folders containing helper functions. + Where should shared types, schemas, and business logic live going forward? + A) Use `src/lib/` as canonical and migrate utils + B) Use `src/utils/` and deprecate lib + C) Keep both: lib for packages, utils for helpers + D) Create new `src/shared/` and consolidate both ⭐ Recommended + +Q2: I don't see a CODEOWNERS file. How should ownership be communicated? + A) No need - solo project + B) Add CODEOWNERS for key directories ⭐ Recommended + C) Document in README files per module + D) Use git history as implicit ownership +``` + +For "Testing Strategy" (even if nothing found): + +``` +Q1: I found a few Jest tests in `src/__tests__/`. Should this pattern continue? + A) Yes, keep all tests in __tests__/ + B) Move to co-located *.test.ts files ⭐ Recommended + C) Use both: __tests__/ for integration, *.test.ts for unit + D) Create separate tests/ directory + +Q2: What test types should be required for new features? + A) Unit tests only + B) Unit + integration tests ⭐ Recommended + C) Unit + integration + e2e tests + D) Based on risk (critical features get more coverage) +``` + +For "Quality & Style" (referencing existing docs from Step 2): + +``` +Q1: Your CONVENTIONS.md says "functions under 50 lines" but doesn't specify + what to do when exceeded. What's the enforcement approach? + A) Soft guideline - suggest refactoring in PR reviews + B) Hard rule - CI fails if functions exceed limit + C) Extract helpers immediately when approaching limit ⭐ Recommended + D) Document exceptions with inline comments + +Q2: I see prettier config but STYLE.md mentions "4 space indents" while + prettier uses 2. Which should be canonical? + A) Update STYLE.md to match prettier config ⭐ Recommended + B) Update prettier to match STYLE.md + C) Keep both - they apply to different file types + D) Remove STYLE.md, rely on tooling +``` + +For **Custom Topic** "GraphQL API Conventions" (4 questions, narrow scope): + +``` +Q1: I found GraphQL schemas in src/graphql/schema/ and API resolvers in src/api/graphql/. + Should schemas and resolvers be co-located? + A) Keep separate - schemas in one place, resolvers grouped by domain + B) Co-locate - each domain folder has schema + resolvers ⭐ Recommended + C) Hybrid - keep schemas separate but organize resolvers by domain + D) Consolidate everything in src/graphql/ + +Q2: Resolver functions range from 10-200 lines. What's the complexity threshold? + A) Keep resolvers thin - delegate to service layer immediately ⭐ Recommended + B) Allow complex resolvers if single responsibility + C) Extract helpers when resolvers exceed 50 lines + D) No limit - resolver complexity matches query complexity + +Q3: No input validation visible in resolvers. Where should GraphQL input validation happen? + A) In resolver functions directly + B) Using GraphQL schema directives ⭐ Recommended + C) In service layer before processing + D) Combination of schema directives + service validation + +Q4: How should GraphQL errors be structured and returned to clients? + A) Use standard GraphQL error format + B) Custom error codes in extensions field ⭐ Recommended + C) HTTP status codes in headers + D) Structured errors with error codes + localized messages +``` + +**Topic Guidance:** + +- **For predefined packs**: Use topic questions from pack-reference.md as guidance +- **For custom topics**: Use clarification scope (aspects/level/scope) to determine question areas +- Ensure questions cover both current state and conventions to establish +- Generate questions even if Explore finds nothing (ask about conventions to establish) + +### Step 6: Conduct Interview (Current Topic Only) + +Present generated questions for the current topic only using AskUserQuestion (max 4 per call): + +```yaml +questions: + - question: "{Generated question 1 based on Explore + topic guidance}" + header: "Q1" + multiSelect: false + options: + - label: "A) {Option based on findings/common patterns}" + description: "{Brief rationale}" + - label: "B) {Option}" + description: "{Brief rationale} ⭐ Recommended" + - label: "C) {Option}" + description: "{Brief rationale}" + - label: "D) {Option}" + description: "{Brief rationale}" + + # ... questions 2-4 +``` + +**Important:** Mark one option per question with "⭐ Recommended" at the end of the description field, based on best practices for the context. + +**Question batching (max 4 per AskUserQuestion call):** + +| Question Count | Batching Strategy | +| -------------- | ------------------------------- | +| 3 questions | Single call [Q1-Q3] | +| 4 questions | Single call [Q1-Q4] | +| 5 questions | Two calls: [Q1-Q4] then [Q5] | +| 6 questions | Two calls: [Q1-Q4] then [Q5-Q6] | +| 7 questions | Two calls: [Q1-Q4] then [Q5-Q7] | + +**Between batches:** Show progress recap before presenting second batch. +Example: "You've answered 4 questions. Next batch: {remaining} questions about {topic}..." + +After completing the interview for the current topic, save responses to `{sessionsPath}{sessionId}.md` (using configured sessionsPath from Step 0), then return to Step 3 to process the next topic. + +Capture responses in Markdown format: + +```markdown +# Interview Session + +**Session ID:** {uuid} +**Date:** {ISO date} +**Timestamp:** {ISO timestamp} + +--- + +## Pack: Architecture & Design Invariants + +**Pack ID:** architecture-design-invariants +**Pack Type:** predefined + +### Question 1 + +**Question:** ... + +**Selected Option:** B + +**Option Text:** ... + +**Notes:** ... + +**Timestamp:** {ISO timestamp} + +--- + +### Question 2 + +**Question:** ... + +**Selected Option:** A + +**Option Text:** ... + +**Notes:** ... + +**Timestamp:** {ISO timestamp} + +--- + +## Pack: GraphQL API Conventions + +**Pack ID:** graphql-api-conventions +**Pack Type:** custom + +**Topic Description:** GraphQL schema organization, resolver patterns, error handling, and input validation conventions + +**Exploration Scope:** + +- **Aspects:** Code patterns and structure, Architecture and design +- **Level:** System-level design +- **Scope:** Specific library/framework + +**Question Count:** 4 + +### Question 1 + +**Question:** ... + +**Selected Option:** B + +**Option Text:** ... + +**Notes:** ... + +**Timestamp:** {ISO timestamp} + +--- + +### Question 2 + +**Question:** ... + +**Selected Option:** C + +**Option Text:** ... + +**Notes:** ... + +**Timestamp:** {ISO timestamp} +``` + +Save to `{sessionsPath}{sessionId}.md` (using configured sessionsPath from Step 0) after each topic interview is completed. + +**After completing all pack interviews**, proceed to Step 7 to generate steerings. + +### Step 7: Generate Steerings (After All Topics Completed) + +**Delegate to general-purpose subagent** using Task tool: + +```yaml +subagent_type: "general-purpose" +description: "Generate steering documents" +prompt: | + Generate steering documents from this interview session. + + {If session file > 50KB, chunk into sections by pack. Provide each pack's Q&A separately. Otherwise provide complete session content.} + + Session Data (Markdown format): + {Provide complete session Markdown content from {sessionsPath}{sessionId}.md file, or chunked by pack if large} + + Output Paths: + - Steerings directory: {steeringsPath} + - Sessions directory: {sessionsPath} + + Existing Documentation & Conventions: + {Provide findings from Step 2 Explore #1 - Documentation & Conventions} + + Repository Context: + {Provide findings from Step 2 Explore #2 - General Repository Context} + + Template Guidelines: + {Provide steering-template.md content} + + Requirements: + + 1. Create one steering file per topic in `{steeringsPath}{filename}.md` (using configured steeringsPath) + + **For predefined packs**, use these concise filenames for ease of reference (full pack context is in file content): + - codebase-topology-ownership → code-ownership.md + - architecture-design-invariants → architecture-invariants.md + - business-domain-contracts → domain-invariants.md + - quality-style-assurance → quality-and-style.md + - testing-verification-strategy → testing-strategy.md + - risk-historical-landmines → risk-registry.md + - security-data-compliance → security-and-compliance.md + - delivery-lifecycle-change-flow → delivery-lifecycle.md + + **For custom topics**, generate filename from packId: + - Use packId directly as filename (already kebab-case) + - Example: "graphql-api-conventions" → graphql-api-conventions.md + - Validate no collisions with predefined pack filenames + + 2. Format requirements: + - Intent: Single concise sentence explaining why these conventions matter + - Rules: Numbered prescriptive statements guiding HOW to do assigned tasks, not proactive commands to do extra work (no Source/Rationale/Applies metadata) + - Practices: Simple format with heading + explanation + optional code example (only when truly needed to clarify) + - Meta: Scope, task types, session info, dependencies + - For custom topics: Include "Topic Type: custom", "Topic Description: {customTopicDescription}", and "Exploration Scope: {aspects/level/scope}" + + 3. Rule style - generate prescriptive/conditional rules, not proactive commands: + + ✅ **Good rules (prescribe methodology, timeless):** + - "When implementing features, keep functions under 50 lines by extracting helpers" + - "New features require unit tests covering happy path and error cases" + - "Throw typed errors with descriptive messages; catch at boundary layers" + - "Extract shared logic used 3+ times into `src/shared/utils/`" + - "Use environment variables for secrets and API keys" + - "Store configuration in YAML files under `config/`" + + ❌ **Bad rules (proactive commands or temporal language):** + - "Proactively refactor complex functions exceeding 50 lines" + - "Add comprehensive test coverage to existing modules" + - "Improve error handling in legacy code" + - "Look for opportunities to extract reusable utilities" + - "Continue using environment variables for secrets" (use "Use" not "Continue using") + - "Keep using YAML for configuration" (use "Store" not "Keep using") + + Rules guide HOW to do the assigned task, not WHAT extra tasks to do. + Rules should be timeless conventions, not references to current state. + + 4. Transform interview responses: + - Synthesize "why" from user's selected options and notes into one sentence for Intent + - Convert selected options into numbered prescriptive rules (following style guidelines in point 3) + - Write rules as timeless prescriptions ("Use X", "Keep Y under Z"), NOT as continuations ("Continue using X", "Keep using Y") + - Remove temporal context from questions (ignore "I found X" framing, just state the convention) + - Provide concrete code examples in Practices section only when needed + + 5. Incorporate existing documentation: + - Reference conventions from existing docs (CONVENTIONS.md, CLAUDE.md, etc.) in relevant steerings + - Align generated rules with documented standards unless interview responses indicate changes + - Consolidate scattered conventions into appropriate steering sections + - Note when interview answers clarify or extend existing documentation + - If existing steerings found, enhance rather than duplicate + + 6. DO NOT include: + - Source/Rationale/Applies fields in rules + - Enforcement section + - Structured subsections (What/How/Example/Anti-pattern) in Practices unless showing multiple approaches + + 7. Code examples should be: + - Optional: Only include when the practice cannot be clearly understood without code + - Concise: 5-15 lines typical, max 25 lines when needed + - Meaningful: Include necessary context (imports, types, file paths) + - Realistic: Use actual patterns from interview responses and codebase + - Focused: One clear concept per example + - NOT full file dumps or trivial snippets + - Many practices are better explained with prose alone + + 8. Validate outputs: + - Intent is 1 sentence + - Rules are numbered prescriptive statements without metadata (following point 3 style) + - Practices have simple format with optional code examples (only when needed) + - Filename is kebab-case matching pack + - File < 200 lines (MUST split if exceeds: use pattern base-name.md + base-name-{subtopic}.md, e.g., architecture-invariants.md → architecture-invariants.md + architecture-invariants-performance.md) + - Document splits in generation summary + - All required sections present + - Recommended options marked with "⭐ Recommended" at exact end of description field + + 9. Generate index.md: + - Create `{steeringsPath}index.md` as table of contents + - List all generated steering files with links + - Provide 1-2 sentence description of what each file covers + - Format as markdown list with relative links + + 10. Return summary of generated files with rule/practice counts + - Report any files that were split due to length constraints +``` + +### Step 8: Present Results + +Show summary from subagent: + +``` +Generated steerings: +- {steeringsPath}code-ownership.md (5 rules, 3 practices) +- {steeringsPath}architecture-invariants.md (7 rules, 4 practices) +- {steeringsPath}testing-strategy.md (6 rules, 3 practices) +- {steeringsPath}index.md (table of contents) + +Session saved: {sessionsPath}{sessionId}.md +``` + +**Agent Consumption Note:** +Agents should read steerings from: {steeringsPath} +This is the canonical location for agent consumption. + +Suggest next steps: + +- Review generated steerings for accuracy +- Edit steerings to add project-specific details +- Commit steerings to git +- Reference in CLAUDE.md or agent instructions +- Run additional interviews for other knowledge areas + +## Example Workflows + +### Example 1: Custom Topic - GraphQL Conventions + +**User request:** "I want to create steerings for GraphQL API conventions" + +**Flow:** + +1. **Step 1**: Detect custom topic "GraphQL API conventions" + - Topic is clear, skip clarification + - Generate: `packId: "graphql-api-conventions"`, `packType: "custom"` +2. **Step 2**: Run docs/conventions discovery (parallel Explore) +3. **Step 3-6**: Process custom topic + - **Step 4**: Dynamic Explore prompt: "Analyze for GraphQL schemas, resolvers, query patterns..." + - **Step 5**: Generate 4-5 questions based on findings (narrow scope) + - **Step 6**: Conduct interview +4. **Step 7**: Generate `steerings/graphql-api-conventions.md` with Meta including custom topic metadata +5. **Step 8**: Present results + +### Example 2: Custom Topic - Terraform Patterns (with clarification) + +**User request:** "Document our infrastructure conventions" + +**Flow:** + +1. **Step 1**: Detect custom topic "infrastructure conventions" (too broad) + - Ask clarification: "What aspects? (Code patterns, Architecture, Process, etc.)" + - User selects: "Code patterns and structure", "Security and compliance" + - Ask level: User selects "File and module patterns" + - Ask scope: User selects "Specific library/framework" + - Refine to: "Terraform module organization and security patterns" + - Generate: `packId: "terraform-patterns"`, `customTopicDescription: "..."` +2. **Step 2**: Run docs/conventions discovery +3. **Step 3-6**: Process custom topic with focused exploration +4. **Step 7**: Generate `steerings/terraform-patterns.md` +5. **Step 8**: Present results + +### Example 3: Mixed - Predefined + Custom + +**User request:** "Run tacit knowledge interview" (no custom topic specified) + +**Flow:** + +1. **Step 1**: No custom topic detected, show predefined packs + - User selects: Pack 2 (Architecture), Pack 5 (Testing) +2. **Step 2**: Run docs/conventions discovery +3. **Step 3-6**: Process Pack 2 → Process Pack 5 +4. **Step 7**: Generate architecture-invariants.md and testing-strategy.md +5. **Step 8**: Present results + +**Later:** + +**User request:** "Now add steerings for React hooks patterns" + +**Flow:** + +1. **Step 1**: Detect custom topic, skip pack selection +2. Process custom topic through Steps 2-8 +3. Generate react-hooks-patterns.md + +### Example 4: Review Mode - Transform Existing Steerings + +**User request:** "Review my existing steerings and fix the format" + +**Flow:** + +1. **Mode Selection**: Detect "review" keyword, enter Review Mode +2. **Step R1**: Auto-detect `./steerings/` directory +3. **Step R2**: Explore agent analyzes 5 files: + - 2 compliant (match format) + - 3 need transformation (verbose rules, missing sections, long code examples) +4. **Step R3**: Show summary to user +5. **Step R4**: User selects "Transform all to standard format" +6. **Step R5**: Subagent transforms 3 files: + - Adds missing Intent sections + - Simplifies rule format + - Trims code examples + - Adds Meta sections +7. **Step R6**: Present transformation results + +**Result:** All steerings now follow Intent → Rules → Practices → Meta format + +## Review Mode (Step R) + +**Use when user wants to review/transform existing steerings.** + +**Note:** Transformation is a sanctioned generator action (not manual editing). Rewriting steerings to match the standard format aligns with repository policy about maintaining consistent structure. + +### Step R1: Locate Existing Steerings + +**Auto-detect steering directories:** + +Use Glob to find common locations: + +- `steerings/` or `./steerings/` +- `.steerings/` +- `docs/steerings/` +- Any path from CLAUDE.md or project docs + +**If multiple locations found or none found:** + +Ask user to specify path using AskUserQuestion: + +```yaml +questions: + - question: "Where are your existing steering files located?" + header: "Location" + multiSelect: false + options: + - label: "./steerings/" + description: "Default location" + - label: "docs/steerings/" + description: "Inside docs folder" + - label: ".steerings/" + description: "Hidden folder" +``` + +### Step R2: Analyze Existing Steerings + +**Use Task tool with Explore agent to analyze all steering files:** + +```yaml +subagent_type: "Explore" +description: "Analyze existing steerings" +prompt: | + Analyze all steering files in {steeringsPath} with medium thoroughness: + + For each .md file, check: + - Structure: Does it follow Intent → Rules → Practices → Meta format? + - Intent section: Is there a single concise "why" sentence? + - Rules section: Are rules numbered and prescriptive? Any metadata/verbose formatting? + - Practices section: Simple format (heading + explanation + code) or complex subsections? + - Meta section: Contains Scope, Task Types, Source Interview, Generated, Dependencies? + - Filename: kebab-case, descriptive? + - File size: Under ~200 lines? + - Code examples: Concise (5-15 lines) or too long/short? + + Report findings: + - Files that match standard format (compliant) + - Files needing transformation (non-compliant with specific issues) + - Missing required sections + - Structural problems + + Provide file paths and specific issues for each non-compliant file. +``` + +### Step R3: Present Review Summary + +Show user: + +``` +Found {N} steering files in {steeringsPath}: + +✅ Compliant (match standard format): +- architecture-invariants.md +- testing-strategy.md + +⚠️ Need transformation: +- code-organization.md: Missing Intent section, rules have verbose metadata +- api-conventions.md: No Meta section, code examples too long (50+ lines) +- error-handling.md: Rules are proactive commands instead of prescriptive conventions +``` + +### Step R4: Ask User What to Do + +```yaml +questions: + - question: "How should non-compliant steerings be handled?" + header: "Action" + multiSelect: false + options: + - label: "Transform all to standard format" + description: "Automatically rewrite non-compliant files to match template" + - label: "Transform specific files" + description: "Choose which files to transform" + - label: "Backup and transform" + description: "Create .bak copies before transforming non-compliant files" + - label: "Generate transformation plan only" + description: "Show what would change without making edits" + - label: "Skip transformation" + description: "Keep files as-is" +``` + +### Step R5: Transform Steerings + +**If user chooses transformation, delegate to general-purpose subagent:** + +```yaml +subagent_type: "general-purpose" +description: "Transform steerings to standard format" +prompt: | + Transform non-compliant steering files to match standard format. + + Backup Policy: + {If user selected "Backup and transform": Before overwriting each file, create a backup copy with .bak extension (e.g., code-ownership.md → code-ownership.md.bak)} + {Otherwise: Overwrite directly without backup} + + Files to transform: + {List of files from Step R3 with specific issues} + + Standard Format (from steering-template.md): + {Provide complete template content} + + Transformation Guidelines: + + **Note:** These transformations align with repository policy. Steerings are generated artifacts maintained through sanctioned generator actions, not manual edits. + + 1. **Intent Section:** + - If missing: Synthesize from existing content (1 sentence "why") + - If too long: Condense to single sentence + - Extract core purpose from introduction/rules + + 2. **Rules Section:** + - Remove Source/Rationale/Applies metadata + - Convert verbose rule format to simple numbered list + - Change proactive commands to prescriptive/conditional rules: + ❌ "Proactively refactor X" → ✅ "When implementing Y, keep X under Z" + ❌ "Continue using X" → ✅ "Use X for Y" + - Keep rules numbered and imperative + - Remove temporal language ("currently", "keep using") + + 3. **Practices Section:** + - Simplify complex subsections (What/How/Example/Anti-pattern) to heading + explanation + code + - Trim code examples to 5-15 lines (max 25) + - Remove full file dumps + - Add file paths as comments in code blocks + - Keep only meaningful examples (remove trivial snippets) + + 4. **Meta Section:** + - Add if missing with: Scope, Task Types, Source Interview (N/A if transformed), Generated (current timestamp), Dependencies + - Use existing metadata if present + - If no Source Interview: Mark as "Source Interview: Transformed from existing documentation" + + 5. **Structural:** + - Ensure single H1 heading + - Make headings unique + - Validate kebab-case filename (rename if needed) + - Split if > 200 lines + + 6. **Preserve Content:** + - Keep domain knowledge and specific conventions intact + - Don't change technical accuracy + - Maintain code example correctness + - Preserve project-specific details + + For each file: + - Read existing content + - Transform according to guidelines + - Write to same path (overwrite) + - Report changes made + + Return summary: + - Files transformed + - Key changes per file + - Any issues encountered +``` + +### Step R5.5: Regenerate Index + +After transformations (especially if files were renamed or split), regenerate index.md: + +**Delegate to general-purpose subagent:** + +```yaml +subagent_type: "general-purpose" +description: "Regenerate steerings index" +prompt: | + Regenerate {steeringsPath}index.md to reflect current steering files. + + Scan {steeringsPath} for all .md files (except index.md itself). + + Create table of contents with: + - Alphabetical list of steering files + - Relative links + - 1-2 sentence description of each file's scope + + Format as markdown list with links. +``` + +### Step R6: Present Transformation Results + +Show summary from subagent: + +``` +Transformed {N} steering files: + +✅ code-organization.md + - Added Intent section: "We organize by feature to enable independent evolution" + - Simplified rules: Removed metadata, converted 8 rules to prescriptive format + - Trimmed 3 code examples from 40+ lines to 10-15 lines + +✅ api-conventions.md + - Added Meta section with Scope: project, Task Types: write-code, setup + - Condensed Practices: Removed What/How subsections, kept simple format + - Split into api-conventions.md (120 lines) and api-error-handling.md (80 lines) + +✅ error-handling.md + - Converted 5 proactive command rules to conditional rules + - Removed temporal language ("continue using" → "use") + +All files now match standard format. +``` + +**Suggest next steps:** + +- Review transformed files +- Commit changes to git +- Run interview flow for new topics if needed + +## Pack Structure + +**8 Available Packs:** (see [pack-reference.md](pack-reference.md)) + +1. Codebase Topology & Ownership +2. Architecture & Design Invariants +3. Business Domain Contracts +4. Quality & Style Assurance +5. Testing & Verification Strategy +6. Risk & Historical Landmines +7. Security, Data & Compliance +8. Delivery Lifecycle & Change Flow + +**How topics are processed:** + +- **Predefined packs** define common topic areas with template Explore prompts +- **Custom topics** allow documenting any technology/domain with dynamic exploration +- Explore agent discovers what exists in codebase for each topic +- Questions are generated dynamically combining findings + topic guidance +- Questions cover both current state AND future plans + +## Tips + +1. **Use custom topics for specific technologies**: Document conventions for frameworks, libraries, or tools not covered by predefined packs (e.g., "Next.js patterns", "Prisma schemas", "Kubernetes configs") +2. **Be specific in answers**: Add notes explaining context and reasoning +3. **Mix predefined and custom**: Use predefined packs for broad areas, custom topics for specific technologies +4. **Review and refine**: Generated steerings are starting points, edit for clarity +5. **Cover future plans**: Answer based on planned conventions, not just what exists today +6. **Layer by scope**: Generate separate steerings for project/team/developer levels + +## Troubleshooting + +**Skill not activating?** + +- Use keywords: "steerings", "tacit knowledge", "interview", "conventions" +- For custom topics: "steerings for X", "document X conventions" +- For review mode: "review steerings", "transform steerings", "fix steerings format" + +**Custom topic too broad?** + +- Answer clarification questions to narrow scope +- Break into multiple focused custom topics instead of one broad topic + +**Questions not relevant?** + +- For custom topics: Provide more specific topic description and clarification +- Explore might need more specific context +- Remember questions cover both present and planned future + +**Custom topic overlaps with predefined pack?** + +- Use predefined pack if it covers 80%+ of what you need +- Use custom topic for specific technology within broader area (e.g., "GraphQL" vs "Architecture") + +**Generated steerings too generic?** + +- Add detailed notes in interview answers +- Include specific examples from your codebase or plans + +**Code examples too long/short?** + +- Generated examples should be 5-15 lines +- Report if subagent produces full file dumps or trivial snippets + +## Reference Files + +- [pack-reference.md](pack-reference.md) — 8 knowledge areas with topic questions, when to use each pack, and outcome mapping +- [steering-template.md](steering-template.md) — Output format and validation rules diff --git a/skills/steerings-generator/interview-packs.md b/skills/steerings-generator/interview-packs.md new file mode 100644 index 0000000..4771dd8 --- /dev/null +++ b/skills/steerings-generator/interview-packs.md @@ -0,0 +1,126 @@ +# 🧠 Interview Questions Pack + +> Purpose: structured interviews to elicit tacit development rules that later become `steerings/` documents. +> Audience: senior engineers, leads, or architects who already maintain part of the repo and its delivery flow. + +--- + +## 1. Codebase Topology & Ownership + +**Goal:** clarify how the repo is organized, what "ownership" means, and when to reuse vs. create new code. + +- Where do shared types, schemas, and business logic live? +- What files or directories are considered "do-not-touch" zones? +- When is it acceptable to add a new module vs. reuse an existing one? +- How do you decide ownership of a package or folder? +- What are the boundaries for editing shared libraries or common utilities? +- How do versioning and `workspace:*` dependencies affect this structure? + +--- + +## 2. Architecture & Design Invariants + +**Goal:** surface the invisible structure that keeps the system stable. + +- What architectural layering patterns are enforced (controller/service/repo, hexagonal, CQRS, etc.)? +- Which dependency directions are allowed or forbidden? +- What naming or import alias rules exist (`@core/*`, `@features/*`, etc.)? +- What design patterns are mandatory or discouraged (events vs. sync calls, DTOs, decorators)? +- What are your caching, concurrency, or idempotency expectations? +- How do you define acceptable performance budgets (latency, memory, N+1 queries)? +- What are the conventions for APIs (REST, GraphQL, gRPC) and versioning/compatibility? + +--- + +## 3. Business Domain Contracts + +**Goal:** capture business logic invariants that constrain code behavior. + +- What are the key domain entities and their invariants? +- How are permissions, roles, and entitlements enforced? +- Are there licensing tiers or feature flags that affect code paths? +- What money-handling or compliance rules shape the design (audit logs, consent, retention)? +- Are there region-specific or client-specific quirks? +- What are the naming or event rules for domain models? + +--- + +## 4. Quality & Style Assurance + +**Goal:** uncover what "high-quality" and "mergeable" mean in this context. + +- What naming, formatting, and readability standards are non-negotiable? +- What must be true before merging a PR ("Definition of Done")? +- How do you enforce dependency discipline (adding/removing libs)? +- What are the rules for logging, error handling, and observability? +- What steps are included in a quality check (`pnpm qc`, lint, type-check, tests)? +- What are examples of commits or PRs that would be rejected outright? + +--- + +## 5. Testing & Verification Strategy + +**Goal:** understand how the team proves code correctness and stability. + +- What test types are required for each layer (unit, integration, e2e, contract)? +- How are test folders and fixtures structured? +- What is your coverage target or philosophy (e.g. 70% meaningful coverage vs. 100%)? +- How do you treat flaky or brittle tests? +- What are "known fragile" modules or flows that require extra attention? +- How are test data and mocks handled (real DB, Docker, fake API, etc.)? + +--- + +## 6. Risk & Historical Landmines + +**Goal:** map the organization's collective memory of past failures. + +- What modules or flows are risky or easy to break? +- What parts of the system "look wrong but are intentional"? +- Are there legacy shims, vendor workarounds, or design debts everyone should know? +- Which incidents led to new "never again" rules? +- What kind of changes are considered dangerous or need special review? + +--- + +## 7. Security, Data & Compliance + +**Goal:** surface hidden security expectations that engineers internalize but rarely document. + +- What are the authentication/authorization boundaries? +- How should secrets and tokens be stored and accessed? +- What patterns are unsafe (direct DB access, unvalidated inputs, inline secrets)? +- How is PII or PHI classified and protected? +- What redaction or anonymization rules apply to logs and metrics? +- What are allowed inbound/outbound service communications? +- How are incidents, breaches, or audit events handled? + +--- + +## 8. Delivery Lifecycle & Change Flow + +**Goal:** make implicit shipping rules explicit. + +- What is the preferred branching model and commit message format? +- How should PR templates and changelogs be filled out? +- What artifacts are required for a feature (migration plan, rollout doc, flag plan)? +- What is the usual rollout → canary → rollback flow? +- How is configuration managed (`.env` → validated config → injected)? +- What approvals or sign-offs are required before deploy? + +--- + +## 📘 Outcome Mapping + +Each interview section contributes to a steering document: + +| Interview Section | Derived Steering | +|--------------------|------------------| +| Codebase Topology & Ownership | `steerings/code-ownership.md` | +| Architecture & Design Invariants | `steerings/architecture-invariants.md` | +| Business Domain Contracts | `steerings/domain-invariants.md` | +| Quality & Style Assurance | `steerings/quality-and-style.md` | +| Testing & Verification Strategy | `steerings/testing-strategy.md` | +| Risk & Historical Landmines | `steerings/risk-registry.md` | +| Security, Data & Compliance | `steerings/security-and-compliance.md` | +| Delivery Lifecycle & Change Flow | `steerings/delivery-lifecycle.md` | diff --git a/skills/steerings-generator/pack-reference.md b/skills/steerings-generator/pack-reference.md new file mode 100644 index 0000000..eb4a461 --- /dev/null +++ b/skills/steerings-generator/pack-reference.md @@ -0,0 +1,394 @@ +# Interview Pack Reference + +This document lists all available interview packs for tacit knowledge extraction. Each pack targets a specific knowledge area and guides context-aware question generation. + +## Available Packs + +### 1. Codebase Topology & Ownership + +**Pack ID:** `codebase-topology-ownership` + +**Goal:** Clarify how the repo is organized, what "ownership" means, and when to reuse vs. create new code. + +**Topics Covered:** + +- Shared types, schemas, and business logic organization +- "Do-not-touch" zones and boundaries +- When to create new modules vs. reuse existing +- Ownership decisions for packages/folders +- Workspace dependencies and versioning + +**Topic Questions (for dynamic question generation):** + +- Where do shared types, schemas, and business logic live? +- What files or directories are considered "do-not-touch" zones? +- When is it acceptable to add a new module vs. reuse an existing one? +- How do you decide ownership of a package or folder? +- What are the boundaries for editing shared libraries or common utilities? +- How do versioning and `workspace:*` dependencies affect this structure? + +**When to Use:** + +- Starting a new project and defining structure +- Onboarding new team members to codebase organization +- Refactoring or reorganizing existing codebases +- Documenting navigation conventions for agents + +**Generated Steering:** `steerings/code-ownership.md` + +--- + +### 2. Architecture & Design Invariants + +**Pack ID:** `architecture-design-invariants` + +**Goal:** Surface the invisible structure that keeps the system stable. + +**Topics Covered:** + +- Architectural layering patterns (controller/service/repo, hexagonal, CQRS) +- Dependency direction rules +- Naming and import alias conventions +- Design patterns (events vs. sync calls, DTOs, decorators) +- Caching, concurrency, idempotency +- Performance budgets +- API conventions and versioning + +**Topic Questions (for dynamic question generation):** + +- What architectural layering patterns are enforced (controller/service/repo, hexagonal, CQRS, etc.)? +- Which dependency directions are allowed or forbidden? +- What naming or import alias rules exist (`@core/*`, `@features/*`, etc.)? +- What design patterns are mandatory or discouraged (events vs. sync calls, DTOs, decorators)? +- What are your caching, concurrency, or idempotency expectations? +- How do you define acceptable performance budgets (latency, memory, N+1 queries)? +- What are the conventions for APIs (REST, GraphQL, gRPC) and versioning/compatibility? + +**When to Use:** + +- Establishing architecture guidelines for new projects +- Aligning team on design patterns +- Creating steerings for how agents should structure features +- Preventing architectural drift + +**Generated Steering:** `steerings/architecture-invariants.md` + +--- + +### 3. Business Domain Contracts + +**Pack ID:** `business-domain-contracts` + +**Goal:** Capture business logic invariants that constrain code behavior. + +**Topics Covered:** + +- Key domain entities and their invariants +- Permissions, roles, and entitlements +- Licensing tiers and feature flags +- Money-handling and compliance rules (audit logs, consent, retention) +- Region-specific or client-specific quirks +- Domain model naming and event rules + +**Topic Questions (for dynamic question generation):** + +- What are the key domain entities and their invariants? +- How are permissions, roles, and entitlements enforced? +- Are there licensing tiers or feature flags that affect code paths? +- What money-handling or compliance rules shape the design (audit logs, consent, retention)? +- Are there region-specific or client-specific quirks? +- What are the naming or event rules for domain models? + +**When to Use:** + +- Documenting business rules that must be preserved +- Onboarding to domain-specific constraints +- Creating steerings for business logic implementation +- Ensuring compliance requirements are explicit + +**Generated Steering:** `steerings/domain-invariants.md` + +--- + +### 4. Quality & Style Assurance + +**Pack ID:** `quality-style-assurance` + +**Goal:** Uncover what "high-quality" and "mergeable" mean in this context. + +**Topics Covered:** + +- Naming, formatting, and readability standards +- Definition of Done (before merging PR) +- Dependency discipline (adding/removing libraries) +- Logging, error handling, and observability rules +- Quality check steps (lint, type-check, tests) +- Examples of unacceptable commits/PRs + +**Topic Questions (for dynamic question generation):** + +- What naming, formatting, and readability standards are non-negotiable? +- What must be true before merging a PR ("Definition of Done")? +- How do you enforce dependency discipline (adding/removing libs)? +- What are the rules for logging, error handling, and observability? +- What steps are included in a quality check (`pnpm qc`, lint, type-check, tests)? +- What are examples of commits or PRs that would be rejected outright? + +**When to Use:** + +- Establishing code quality standards +- Defining "done" criteria for agents +- Creating pre-commit or CI check guidelines +- Documenting what makes code mergeable + +**Generated Steering:** `steerings/quality-and-style.md` + +--- + +### 5. Testing & Verification Strategy + +**Pack ID:** `testing-verification-strategy` + +**Goal:** Understand how the team proves code correctness and stability. + +**Topics Covered:** + +- Required test types per layer (unit, integration, e2e, contract) +- Test folder and fixture structure +- Coverage targets and philosophy +- Handling flaky or brittle tests +- Known fragile modules requiring extra attention +- Test data and mock strategies (real DB, Docker, fake API) + +**Topic Questions (for dynamic question generation):** + +- What test types are required for each layer (unit, integration, e2e, contract)? +- How are test folders and fixtures structured? +- What is your coverage target or philosophy (e.g. 70% meaningful coverage vs. 100%)? +- How do you treat flaky or brittle tests? +- What are "known fragile" modules or flows that require extra attention? +- How are test data and mocks handled (real DB, Docker, fake API, etc.)? + +**When to Use:** + +- Defining testing requirements for new projects +- Creating steerings for test generation +- Documenting test structure conventions +- Setting coverage expectations + +**Generated Steering:** `steerings/testing-strategy.md` + +--- + +### 6. Risk & Historical Landmines + +**Pack ID:** `risk-historical-landmines` + +**Goal:** Map the organization's collective memory of past failures. + +**Topics Covered:** + +- Risky or easy-to-break modules/flows +- Intentional "looks wrong" code +- Legacy shims and vendor workarounds +- Design debts everyone should know +- Incidents that led to "never again" rules +- Changes requiring special review + +**Topic Questions (for dynamic question generation):** + +- What modules or flows are risky or easy to break? +- What parts of the system "look wrong but are intentional"? +- Are there legacy shims, vendor workarounds, or design debts everyone should know? +- Which incidents led to new "never again" rules? +- What kind of changes are considered dangerous or need special review? + +**When to Use:** + +- Preserving institutional knowledge +- Warning agents about dangerous areas +- Documenting known issues and workarounds +- Creating "be careful here" steerings + +**Generated Steering:** `steerings/risk-registry.md` + +--- + +### 7. Security, Data & Compliance + +**Pack ID:** `security-data-compliance` + +**Goal:** Surface hidden security expectations that engineers internalize but rarely document. + +**Topics Covered:** + +- Authentication/authorization boundaries +- Secrets and token storage/access +- Unsafe patterns (direct DB access, unvalidated inputs, inline secrets) +- PII/PHI classification and protection +- Redaction and anonymization rules for logs/metrics +- Allowed inbound/outbound service communications +- Incident, breach, and audit event handling + +**Topic Questions (for dynamic question generation):** + +- What are the authentication/authorization boundaries? +- How should secrets and tokens be stored and accessed? +- What patterns are unsafe (direct DB access, unvalidated inputs, inline secrets)? +- How is PII or PHI classified and protected? +- What redaction or anonymization rules apply to logs and metrics? +- What are allowed inbound/outbound service communications? +- How are incidents, breaches, or audit events handled? + +**When to Use:** + +- Documenting security requirements +- Creating steerings for secure coding +- Ensuring compliance with data protection rules +- Defining authentication/authorization patterns + +**Generated Steering:** `steerings/security-and-compliance.md` + +--- + +### 8. Delivery Lifecycle & Change Flow + +**Pack ID:** `delivery-lifecycle-change-flow` + +**Goal:** Make implicit shipping rules explicit. + +**Topics Covered:** + +- Branching model and commit message format +- PR templates and changelog requirements +- Required artifacts (migration plan, rollout doc, flag plan) +- Rollout → canary → rollback flow +- Configuration management (`.env` → validated config → injected) +- Required approvals and sign-offs + +**Topic Questions (for dynamic question generation):** + +- What is the preferred branching model and commit message format? +- How should PR templates and changelogs be filled out? +- What artifacts are required for a feature (migration plan, rollout doc, flag plan)? +- What is the usual rollout → canary → rollback flow? +- How is configuration managed (`.env` → validated config → injected)? +- What approvals or sign-offs are required before deploy? + +**When to Use:** + +- Defining deployment workflows +- Creating steerings for release processes +- Documenting change management procedures +- Setting PR and commit standards + +**Generated Steering:** `steerings/delivery-lifecycle.md` + +--- + +## How to Choose Packs + +### By Development Phase + +**Starting a New Project:** + +- Run: 1 (Topology), 2 (Architecture), 4 (Quality), 5 (Testing) +- Establishes foundational structure and standards + +**Scaling an Existing Project:** + +- Run: All available packs +- Captures current practices before they become implicit + +**Onboarding Phase:** + +- Run: 1 (Topology), 2 (Architecture), 6 (Risk), 7 (Security) +- Documents "how we do things here" and "what to watch out for" + +**Production Readiness:** + +- Run: 5 (Testing), 7 (Security), 8 (Delivery) +- Ensures shipping and operational standards are defined + +### By Knowledge Gap + +**"Where should this code go?"** + +- Run: 1 (Codebase Topology) + +**"What patterns should we follow?"** + +- Run: 2 (Architecture Invariants), 4 (Quality & Style) + +**"How should we test?"** + +- Run: 5 (Testing & Verification) + +**"What are the risks?"** + +- Run: 6 (Risk & Historical Landmines) + +**"How do we ship safely?"** + +- Run: 7 (Security), 8 (Delivery Lifecycle) + +**"What business rules matter?"** + +- Run: 3 (Business Domain Contracts) + +--- + +## Pack Usage Model + +Packs serve as **topic guidance** for generating context-aware questions. They do NOT contain pre-written questions. + +**How packs are used:** + +1. **User selects pack** (e.g., "Architecture & Design Invariants") +2. **Explore agent analyzes codebase** (finds existing patterns) +3. **Questions are generated dynamically** using: + - Findings from Explore (what exists) + - Topics from pack guidance (what to ask about, including future plans) +4. **Interview conducted** with generated questions +5. **Steering generated** in simplified format + +**Example:** + +For "Testing & Verification Strategy": + +- Explore finds: A few test files in `src/__tests__/`, jest.config.js, no coverage config +- Pack guidance: "What test types should be required? How should test folders be structured? What coverage target?" +- Generated questions combine both: + - "I see Jest tests in `src/__tests__/`. Should this pattern continue, or move tests closer to source files?" + - "What test types should be required for each layer (unit, integration, e2e)?" + - "What coverage target makes sense for this project?" + +--- + +## Extensibility + +To add a new interview pack: + +1. **Add to interview-packs.md:** New section with goal and topic bullets +2. **Add to this file:** Pack ID, goal, topics, when to use, generated steering name +3. **Update SKILL.md:** Add Explore prompt guidance for the new pack +4. **Add to outcome mapping:** Steering filename for the new pack + +The tacit-knowledge skill will automatically support new packs when they're added to these reference files. + +--- + +## Outcome Mapping + +Each interview pack generates a specific steering document: + +| Pack | Generated Steering | +| ----------------------------------- | -------------------------------------- | +| 1. Codebase Topology & Ownership | `steerings/code-ownership.md` | +| 2. Architecture & Design Invariants | `steerings/architecture-invariants.md` | +| 3. Business Domain Contracts | `steerings/domain-invariants.md` | +| 4. Quality & Style Assurance | `steerings/quality-and-style.md` | +| 5. Testing & Verification Strategy | `steerings/testing-strategy.md` | +| 6. Risk & Historical Landmines | `steerings/risk-registry.md` | +| 7. Security, Data & Compliance | `steerings/security-and-compliance.md` | +| 8. Delivery Lifecycle & Change Flow | `steerings/delivery-lifecycle.md` | diff --git a/skills/steerings-generator/steering-template.md b/skills/steerings-generator/steering-template.md new file mode 100644 index 0000000..47e14f1 --- /dev/null +++ b/skills/steerings-generator/steering-template.md @@ -0,0 +1,331 @@ +# Steering Template + +This template defines the structure for generated steering documents. All steerings follow the **Intent → Rules → Practices → Meta** format. + +--- + +## Standard Steering Structure + +```markdown +# {Steering Title} + +{Brief 1-2 sentence overview of what this steering covers} + +## Intent (Why) + +{Single concise sentence explaining why these conventions matter} + +## Rules (What) + +{Numbered list of concrete, enforceable rules. Keep statements imperative and actionable.} + +1. {Clear rule statement} +2. {Clear rule statement} +3. {Clear rule statement} + +{Continue for 5-10 rules per steering} + +## Practices (How) + +{Concrete examples showing how to apply the rules. Keep format simple: heading + explanation + code.} + +### {Practice Category 1} + +{Brief explanation of the practice} +``` + +{Code example, file structure example, or workflow example} + +``` + +--- + +### {Practice Category 2} + +{Brief explanation of the practice} + +``` + +{Code/workflow example} + +``` + +--- + +{Continue for 3-5 practice categories} + +## Meta + +**Scope**: {project | team | developer} + +**Task Types**: {comma-separated list: write-code, write-tests, refactor, etc.} + +**Source Interview**: +- Session ID: `{sessionId}` +- Date: `{YYYY-MM-DD}` +- Pack: `{pack-id}` + +**Generated**: `{ISO 8601 timestamp}` + +**Dependencies**: {Related steerings that should be read together} +- `{other-steering-name.md}` — {Why it's related} +``` + +--- + +## Filename Conventions + +Steering filenames must: + +- Use kebab-case (lowercase with hyphens) +- Reflect the knowledge area +- Be descriptive but concise (2-4 words) + +**Examples:** + +- `codebase-topology.md` +- `architecture-invariants.md` +- `testing-strategy.md` + +--- + +## Content Guidelines + +### Intent Section + +**Requirement**: Single concise sentence explaining the core "why" + +**Good Intent:** + +```markdown +## Intent (Why) + +We organize code by feature rather than by layer to keep related code co-located, enable feature-level ownership, and support independent feature evolution. +``` + +**Weak Intent:** + +```markdown +## Intent (Why) + +This is how we organize code. +``` + +### Rules Section + +**Requirement**: Numbered prescriptive statements without metadata + +Rules should guide **HOW to do assigned tasks**, not tell agents to do extra work. Use conditional ("When X, do Y") or prescriptive ("Structure X as Y") patterns. + +**Rule Patterns:** + +✅ **Conditional rules:** +```markdown +1. When implementing features, keep functions under 50 lines by extracting helpers +2. When refactoring, extract functions with single responsibilities +``` + +✅ **Prescriptive rules:** +```markdown +1. Place shared types and utilities in `src/shared/` +2. Features must not import from other features +3. Use TypeScript path aliases (@core/_, @features/_) for all internal imports +``` + +✅ **Scoped requirement rules:** +```markdown +1. New features require unit tests covering happy path and error cases +2. Extract shared logic used 3+ times into `src/shared/utils/` +``` + +❌ **Avoid proactive commands (tell agent to do extra work):** +```markdown +1. Proactively refactor complex functions exceeding 50 lines +2. Add comprehensive test coverage to existing modules +3. Improve error handling in legacy code +4. Look for opportunities to extract reusable utilities +``` + +**Avoid:** + +- Proactive commands that tell agents to do work outside assigned task scope +- Adding Source/Rationale/Applies metadata +- Overly verbose explanations +- Weak statements like "Try to keep code organized" + +### Practices Section + +**Requirement**: Simple format with heading + explanation + code example + +**Good Practice:** + +```markdown +### Creating a New Shared Utility + +Place reusable functions in `src/shared/utils/`: + +\`\`\`typescript +// src/shared/utils/format-currency.ts +export function formatCurrency(amount: number): string { +return new Intl.NumberFormat('en-US', { +style: 'currency', +currency: 'USD' +}).format(amount); +} +\`\`\` +``` + +**Avoid:** + +- Structured subsections (What/How/Example/Anti-pattern) unless multiple competing approaches exist +- Overly detailed step-by-step procedures +- Generic advice without concrete examples + +**When to add structure:** +Only when there are multiple valid approaches to show. Example: + +```markdown +### Handling Cross-Module Communication + +**Option 1: Direct calls** (same module) +\`\`\`typescript +await this.updateInventory(order.items); +\`\`\` + +**Option 2: Domain events** (cross-module) +\`\`\`typescript +this.eventBus.publish(new OrderCompletedEvent(order)); +\`\`\` +``` + +--- + +## Meta Section Guidelines + +### Scope Values + +- `project`: Applies to all code in this repository +- `team`: Applies to this team's work across projects +- `developer`: Personal conventions for individual contributors + +### Task Type Values + +Common task types: + +- `write-code` — Implementing new features +- `write-tests` — Creating tests +- `write-docs` — Documentation +- `refactor` — Restructuring code +- `review` — Code review +- `debug` — Bug fixing +- `setup` — Project configuration + +### Dependencies + +List related steerings: + +```markdown +**Dependencies**: + +- `architecture-invariants.md` — Defines layer boundaries referenced here +- `testing-strategy.md` — Impacts module structure for testability +``` + +--- + +## Validation Checklist + +Before finalizing a steering: + +- [ ] Single H1 heading present +- [ ] Intent is one concise sentence +- [ ] Rules are numbered imperative statements (no metadata) +- [ ] Practices use simple format (heading + explanation + code) +- [ ] No Enforcement section +- [ ] Filename is kebab-case +- [ ] All required sections present (Intent, Rules, Practices, Meta) +- [ ] File is < 200 lines (split if longer) +- [ ] Meta section complete + +--- + +## Code Example Guidelines + +Code snippets in Practices section should be: + +**Concise**: Show only the essential pattern (5-15 lines typical, max 25 lines) + +- Focus on the concept being demonstrated +- Omit boilerplate unless it's part of the pattern +- Use `// ...` to indicate omitted code when helpful + +**Meaningful**: Include enough context to understand the pattern + +- Add file paths as comments (`// src/features/auth/auth.service.ts`) +- Include necessary imports if they're part of the convention +- Show types/interfaces if they clarify the pattern + +**Realistic**: Use actual project conventions + +- Match the naming conventions from interview responses +- Use real imports and paths from the codebase +- Reflect actual patterns, not generic examples + +**Focused**: One clear concept per example + +- Don't mix multiple patterns in one snippet +- If showing alternatives, separate them clearly +- Avoid unrelated details + +**Good example:** + +```typescript +// src/features/auth/auth.service.ts +export class AuthService { + async login(email: string): Promise { + const user = await this.userRepo.findByEmail(email); + return this.sessionManager.create(user); + } +} +``` + +**Avoid:** + +- Full file dumps (50+ lines of code) +- Trivial examples without context (`const x = 1`) +- Multiple unrelated patterns in one snippet +- Placeholder code like `// TODO: implement` +- Generic "hello world" examples that don't reflect real patterns + +--- + +## Splitting Large Steerings + +If a steering exceeds ~200 lines, split it logically: + +**Example**: `architecture-invariants.md` (too large) + +**Split into**: + +- `architecture-layering.md` — Layer structure and dependencies +- `architecture-imports.md` — Import rules and path aliases +- `architecture-events.md` — Event-driven patterns + +Cross-reference in Meta dependencies. + +--- + +## Outcome Mapping + +Each interview pack generates a specific steering document: + +| Pack | Generated Steering | +| -------------------------------- | ---------------------------- | +| Codebase Topology & Ownership | `code-ownership.md` | +| Architecture & Design Invariants | `architecture-invariants.md` | +| Business Domain Contracts | `domain-invariants.md` | +| Quality & Style Assurance | `quality-and-style.md` | +| Testing & Verification Strategy | `testing-strategy.md` | +| Risk & Historical Landmines | `risk-registry.md` | +| Security, Data & Compliance | `security-and-compliance.md` | +| Delivery Lifecycle & Change Flow | `delivery-lifecycle.md` |