Initial commit
This commit is contained in:
Zhongwei Li
1288
skills/steerings-generator/SKILL.md
Normal file
1288
skills/steerings-generator/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
126
skills/steerings-generator/interview-packs.md
Normal file
126
skills/steerings-generator/interview-packs.md
Normal 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
394
skills/steerings-generator/pack-reference.md
Normal 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
331
skills/steerings-generator/steering-template.md
Normal 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` |
|
||||
Reference in New Issue
Block a user