zhongwei/gh-timurkhakhalev-cc-plugins-steerings-generator-cc-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:02:04 +08:00
commit a91a875f01
7 changed files with 2211 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# steerings-generator
Extract tacit engineering knowledge through guided interviews and generate structured steerings

57
plugin.lock.json Normal file
View File

@@ -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": []
}
}

1288
skills/steerings-generator/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

126
skills/steerings-generator/interview-packs.md Normal file
View File

@@ -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` |

394
skills/steerings-generator/pack-reference.md Normal file
View File

@@ -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` |

331
skills/steerings-generator/steering-template.md Normal file
View File

@@ -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<Session> {
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` |