@dzhechkov/p-replicator 1.0.0

package/templates/.claude/skills/knowledge-extractor/references/artifact-categories.md

@@ -0,0 +1,342 @@
+# Artifact Categories Reference
+
+Detailed criteria for classifying extracted knowledge into 7 toolkit categories.
+
+---
+
+## Category 1: Skills
+
+**Directory:** `skills/[name]/SKILL.md`
+
+**What belongs:**
+- New techniques or improved approaches to common tasks
+- Multi-step workflows that can be reused across projects
+- AI-assisted capabilities (Claude Code skill definitions)
+
+**Criteria:**
+- Involves a multi-step process (not a single function)
+- Has clear input → transformation → output
+- Can be described with trigger patterns
+- Benefits from documentation (when to use, anti-patterns)
+
+**Structure:** Follow `pipeline-forge` skill anatomy
+```
+skills/[name]/
+├── SKILL.md
+├── references/    (optional)
+└── templates/     (optional)
+```
+
+**Examples:**
+- Better database migration technique
+- API integration pattern with retry + circuit breaker
+- Testing strategy for event-driven systems
+
+**NOT a skill:** A single utility function (→ snippet), a config file (→ template)
+
+---
+
+## Category 2: Commands
+
+**Directory:** `commands/[name].md`
+
+**What belongs:**
+- Slash commands for Claude Code
+- CLI utilities that automate common dev tasks
+- Build/deploy/test shortcuts
+
+**Criteria:**
+- Invoked explicitly by the user (not automatic)
+- Has clear arguments and expected output
+- Saves significant time on repetitive tasks
+- Works across different projects (not project-specific)
+
+**Structure:** Claude Code command format
+```markdown
+---
+description: What the command does. $ARGUMENTS: what it expects.
+---
+
+# /command-name $ARGUMENTS
+
+## Steps
+1. [step]
+2. [step]
+```
+
+**Examples:**
+- `/api-endpoint` generates CRUD for a resource
+- `/db-migrate` runs migration with safety checks
+- `/perf-check` profiles and reports performance
+
+**NOT a command:** An automation trigger (→ hook), a file structure (→ template)
+
+---
+
+## Category 3: Hooks
+
+**Directory:** `.claude/settings.json` or `.claude/hooks/`
+
+**What belongs:**
+- Pre-commit validation hooks
+- Post-task automation (auto-format, auto-test)
+- CI pipeline triggers
+- Git hooks for quality gates
+- Claude Code hooks (PreToolUse, PostToolUse, Stop)
+
+**Criteria:**
+- Triggered automatically (not manually invoked)
+- Attached to a specific event (commit, merge, task completion)
+- Enforces a quality standard or automates a chore
+- Low overhead (runs fast, doesn't block workflow)
+
+**Structure:**
+```json
+{
+  "hooks": {
+    "EventName": [{
+      "matcher": "ToolName",
+      "command": "echo 'hook output'"
+    }]
+  }
+}
+```
+
+**Examples:**
+- Auto-validate OpenAPI schema on save
+- Run linter on pre-commit
+- Remind about harvest on release tag
+- Auto-commit insights on Stop
+
+**NOT a hook:** A manual command (→ command), a constraint (→ rule)
+
+---
+
+## Category 4: Rules
+
+**Directory:** `rules/[name].md`
+
+**What belongs:**
+- Constraints and limitations discovered empirically
+- "Don't do X because Y" lessons
+- Framework/language quirks worth remembering
+- Security constraints
+- Performance constraints
+- AI (Claude Code) limitations and workarounds
+
+**Criteria:**
+- States a constraint, not a how-to
+- Has a clear "because" (reason, not just assertion)
+- Applies beyond the source project
+- Saves future debugging time
+
+**Structure:**
+```markdown
+# Rule: [Short Name]
+
+## Rule
+[Don't do X because Y]
+
+## Why
+[Technical explanation]
+
+## Example (what goes wrong)
+[Code or scenario]
+
+## Correct Approach
+[What to do instead]
+
+## Scope
+Universal | Language: [lang] | Framework: [fw]
+
+## Expiry
+Permanent | Check after [condition]
+```
+
+**Examples:**
+- "Don't use nested generics >3 levels — Claude Code loses context"
+- "Always use parameterized queries — never string concat for SQL"
+- "Redis SCAN is O(N) — don't use for large keyspaces in hot path"
+
+**NOT a rule:** A code pattern (→ pattern), an automation (→ hook)
+
+---
+
+## Category 5: Templates
+
+**Directory:** `templates/[name]/` or standalone files
+
+**What belongs:**
+- Reusable file structures (Dockerfile, CI config, etc.)
+- Project scaffold templates
+- Configuration file templates
+- Document templates (ADR, RFC, etc.)
+
+**Criteria:**
+- Has `{{PLACEHOLDERS}}` for project-specific values
+- Works by filling in parameters, not rewriting
+- Structure is more valuable than content
+- Tested with at least one real project
+
+**Structure:**
+```markdown
+# Template: [Name]
+
+## Parameters
+| Placeholder | Description | Default | Required |
+|------------|-------------|---------|----------|
+| {{NAME}} | [desc] | [default] | YES/NO |
+
+## Template Content
+[the actual template with placeholders]
+
+## Usage
+[how to use this template]
+```
+
+**Examples:**
+- Dockerfile for Node.js + PostgreSQL
+- GitHub Actions CI/CD pipeline
+- ADR (Architecture Decision Record) template
+- docker-compose.yml for dev environment
+
+**NOT a template:** Code logic (→ snippet/pattern), a process (→ skill)
+
+---
+
+## Category 6: Patterns
+
+**Directory:** `patterns/[name].md` or `docs/patterns/`
+
+**What belongs:**
+- Architectural approaches documented as knowledge
+- Design patterns adapted to specific contexts
+- Integration patterns between systems
+- Error handling strategies
+- Data access patterns
+
+**Criteria:**
+- Describes an APPROACH, not specific code
+- Has multiple valid implementations
+- Includes trade-offs and when-to-use/when-not
+- More than just a code snippet — includes reasoning
+
+**Structure:**
+```markdown
+# Pattern: [Name]
+
+## Intent
+[What problem this pattern solves]
+
+## When to Use
+[Conditions]
+
+## When NOT to Use
+[Anti-conditions]
+
+## Structure
+[Diagram or pseudocode]
+
+## Implementation Variants
+### Variant A: [context]
+[implementation]
+
+### Variant B: [context]
+[implementation]
+
+## Trade-offs
+| Pro | Con |
+|-----|-----|
+| [+] | [-] |
+
+## Related Patterns
+[links to complementary or alternative patterns]
+```
+
+**Examples:**
+- Rate limiting (in-memory vs. Redis-backed)
+- Circuit breaker with fallback
+- Event sourcing + CQRS
+- Repository pattern with caching
+
+**NOT a pattern:** Specific code (<50 lines → snippet), a constraint (→ rule)
+
+---
+
+## Category 7: Snippets
+
+**Directory:** `snippets/[language]/[name].[ext]` or inline in docs
+
+**What belongs:**
+- Small, self-contained code fragments (<50 lines)
+- Utility functions that solve common problems
+- One-liners or short helpers
+- Type definitions / interfaces that are universal
+
+**Criteria:**
+- Self-contained (works without project context)
+- Under 50 lines of code
+- Solves a common problem
+- No domain-specific dependencies
+- Can be copy-pasted and used immediately
+
+**Structure:**
+```markdown
+# Snippet: [Name]
+
+**Language:** [lang]
+**Lines:** [N]
+**Dependencies:** None | [list]
+
+## Code
+\`\`\`[lang]
+[code]
+\`\`\`
+
+## Usage
+[how and when to use]
+```
+
+**Examples:**
+- Universal retry with exponential backoff
+- Safe JSON parse with default
+- Debounce/throttle function
+- Type-safe environment variable reader
+
+**NOT a snippet:** >50 lines (→ pattern), a process (→ skill), a config (→ template)
+
+---
+
+## Decision Flowchart
+
+```
+Start with a finding
+    │
+    ├── Is it a multi-step process/workflow?
+    │   ├── YES → Skill or Command
+    │   │   ├── User-invoked? → Command
+    │   │   └── AI-assisted workflow? → Skill
+    │   └── NO ↓
+    │
+    ├── Is it triggered automatically?
+    │   ├── YES → Hook
+    │   └── NO ↓
+    │
+    ├── Is it a constraint / "don't do X"?
+    │   ├── YES → Rule
+    │   └── NO ↓
+    │
+    ├── Is it a file/config structure?
+    │   ├── YES → Template
+    │   └── NO ↓
+    │
+    ├── Is it <50 lines of executable code?
+    │   ├── YES → Snippet
+    │   └── NO ↓
+    │
+    ├── Is it an architectural approach?
+    │   ├── YES → Pattern
+    │   └── NO → Reconsider extraction
+    │
+    └── END
+```

package/templates/.claude/skills/knowledge-extractor/references/decontextualization-guide.md

@@ -0,0 +1,247 @@
+# Decontextualization Guide
+
+How to transform project-specific artifacts into universal, reusable toolkit entries.
+
+---
+
+## Core Principle
+
+> **Decontextualization is NOT renaming variables. It's extracting the PRINCIPLE
+> and providing an implementation that works in any context.**
+
+The goal is to separate the **universal insight** from the **project-specific implementation**.
+
+---
+
+## The Decontextualization Checklist
+
+For every artifact, verify each item before it enters the toolkit:
+
+### 1. Names & References
+- [ ] No company/product names → replaced with `{{PROJECT_NAME}}` or generic
+- [ ] No team member names → removed or replaced with roles
+- [ ] No project-specific variable names → use descriptive generic names
+- [ ] No internal URLs → removed or parameterized
+- [ ] No specific database/table names → generic schema references
+
+### 2. Paths & Configuration
+- [ ] No absolute paths → relative or `{{PROJECT_ROOT}}`
+- [ ] No hardcoded ports → `{{PORT}}` or env variable
+- [ ] No hardcoded API keys → `{{API_KEY}}` with note about secure storage
+- [ ] No environment-specific configs → parameterized with defaults
+- [ ] Config values documented in parameter table
+
+### 3. Dependencies
+- [ ] External dependencies listed explicitly
+- [ ] Version constraints documented
+- [ ] Alternative libraries mentioned (if applicable)
+- [ ] No implicit dependencies (things that "just work" because of project setup)
+
+### 4. Context
+- [ ] Works without the original project's other modules
+- [ ] Import/require statements are generic or documented
+- [ ] No circular dependencies with project code
+- [ ] Can be copy-pasted into new project and work (with documented setup)
+
+---
+
+## Decontextualization Techniques
+
+### Technique 1: Extract Interface
+
+**Before:**
+```typescript
+// Tightly coupled to UserService
+function rateLimitMiddleware(userService: UserService) {
+  return (req: Request) => {
+    const user = userService.getUser(req.userId);
+    if (user.requestCount > user.plan.limit) {
+      throw new RateLimitError();
+    }
+  };
+}
+```
+
+**After:**
+```typescript
+// Generic — works with any identity provider
+interface RateLimitSubject {
+  id: string;
+  currentCount: number;
+  limit: number;
+}
+
+interface RateLimitProvider {
+  getSubject(requestId: string): Promise<RateLimitSubject>;
+  increment(subjectId: string): Promise<void>;
+}
+
+function rateLimitMiddleware(provider: RateLimitProvider) {
+  return async (req: Request) => {
+    const subject = await provider.getSubject(req.headers['x-subject-id']);
+    if (subject.currentCount >= subject.limit) {
+      throw new RateLimitError(subject.id, subject.limit);
+    }
+    await provider.increment(subject.id);
+  };
+}
+```
+
+**What changed:** Replaced concrete `UserService` with generic `RateLimitProvider` interface.
+
+### Technique 2: Parameterize
+
+**Before:**
+```yaml
+# docker-compose.yml for the e-commerce project
+services:
+  api:
+    build: ./backend
+    ports:
+      - "3000:3000"
+    environment:
+      DATABASE_URL: postgres://ecommerce:secret@db:5432/ecommerce_dev
+  db:
+    image: postgres:15
+    environment:
+      POSTGRES_DB: ecommerce_dev
+      POSTGRES_PASSWORD: secret
+```
+
+**After:**
+```yaml
+# Template: Node.js + PostgreSQL Docker Compose
+# Parameters: {{SERVICE_NAME}}, {{PORT}}, {{DB_NAME}}, {{DB_PASSWORD}}
+services:
+  {{SERVICE_NAME}}:
+    build: ./backend
+    ports:
+      - "${PORT:-3000}:${PORT:-3000}"
+    environment:
+      DATABASE_URL: postgres://${DB_USER:-app}:${DB_PASSWORD}@db:5432/${DB_NAME}
+  db:
+    image: postgres:${POSTGRES_VERSION:-15}
+    environment:
+      POSTGRES_DB: ${DB_NAME}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+```
+
+**What changed:** All project-specific values → environment variables with defaults.
+
+### Technique 3: Document the Principle
+
+**Before (code comment in project):**
+```
+// HACK: Don't use Promise.all for Stripe API calls — it triggers rate limit
+```
+
+**After (toolkit rule):**
+```markdown
+# Rule: Sequential External API Calls for Rate-Limited Services
+
+## Rule
+When calling rate-limited external APIs (Stripe, Twilio, etc.),
+use sequential execution instead of Promise.all/parallel.
+
+## Why
+Rate-limited APIs count requests per time window. Parallel requests
+arrive simultaneously and exceed the limit, causing failures that
+are hard to debug (they appear intermittent).
+
+## Example (what goes wrong)
+\`\`\`typescript
+// ❌ BAD — triggers rate limit
+const results = await Promise.all(
+  items.map(item => stripeApi.createCharge(item))
+);
+// Error: Rate limit exceeded (429) — but only sometimes!
+\`\`\`
+
+## Correct Approach
+\`\`\`typescript
+// ✅ GOOD — respects rate limits
+const results = [];
+for (const item of items) {
+  results.push(await externalApi.call(item));
+  // Optional: add small delay for strict rate limits
+}
+\`\`\`
+
+## Scope
+Universal — applies to any rate-limited external API
+
+## Variants
+- With retry + backoff for transient failures
+- With queue for high-volume scenarios
+- With batch endpoint if API supports it
+```
+
+**What changed:** Specific Stripe hack → universal rule about rate-limited APIs.
+
+### Technique 4: Provide Variants
+
+When the original implementation is language/framework-specific,
+provide multiple variants:
+
+```markdown
+# Pattern: Retry with Exponential Backoff
+
+## Variant A: TypeScript (Node.js)
+\`\`\`typescript
+async function retry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
+  for (let i = 0; i < maxRetries; i++) {
+    try { return await fn(); }
+    catch (e) {
+      if (i === maxRetries - 1) throw e;
+      await sleep(Math.pow(2, i) * 1000);
+    }
+  }
+  throw new Error('unreachable');
+}
+\`\`\`
+
+## Variant B: Python
+\`\`\`python
+async def retry(fn, max_retries=3):
+    for i in range(max_retries):
+        try: return await fn()
+        except Exception as e:
+            if i == max_retries - 1: raise
+            await asyncio.sleep(2 ** i)
+\`\`\`
+
+## Variant C: Rust
+\`\`\`rust
+async fn retry<F, T, E>(f: F, max_retries: u32) -> Result<T, E>
+where F: Fn() -> Pin<Box<dyn Future<Output = Result<T, E>>>> {
+    // ...
+}
+\`\`\`
+```
+
+---
+
+## Red Flags (Incomplete Decontextualization)
+
+| Red Flag | Problem | Fix |
+|----------|---------|-----|
+| `import { UserModel } from '../models'` | Project-specific import | Use interface/generic |
+| `const API_URL = 'https://api.mycompany.com'` | Hardcoded URL | Use env variable |
+| `// Works because we use Express 4.x` | Implicit dependency | Document explicitly |
+| Function name `handleStripeWebhook` | Too specific | Rename to `handleWebhook` |
+| `config.ecommerceSettings.taxRate` | Domain-specific config | Extract to parameters |
+| Only works with PostgreSQL | Missing variants | Add alternative DB support |
+
+---
+
+## Decontextualization by Category
+
+| Category | Key Focus |
+|----------|-----------|
+| **Skills** | Remove domain context, keep methodology |
+| **Commands** | Parameterize paths and args, document tool deps |
+| **Hooks** | Make trigger event configurable |
+| **Rules** | State universal principle, not project symptom |
+| **Templates** | Replace ALL hardcoded values with `{{PLACEHOLDERS}}` |
+| **Patterns** | Describe the APPROACH with multiple implementations |
+| **Snippets** | Ensure standalone execution, document dependencies |