# Project Completion Knowledge Extraction

> Distribute completed project work from sandbox to proper repositories using three-tier documentation architecture. Ensures code, knowledge, and patterns are extracted and properly organized when projects complete. Use when this capability is needed.

- Skill: `tomevault-io/project-completion-knowledge-extraction` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/project-completion-knowledge-extraction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/project-completion-knowledge-extraction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/project-completion-knowledge-extraction

---


# Project Completion: Knowledge Extraction Pattern

**Pattern Type**: Project Management
**Applies To**: All projects that deploy to production or create reusable patterns
**Last Updated**: 2025-10-07
**Validated**: feature-salesjournaltoreact (production deployment)

---

## Core Principle

**Sandbox work must be distributed to proper repositories when complete**.

Projects in `projects/active/` are SANDBOXES for coordination. When projects complete:
- Code goes to production repositories
- Documentation goes to multiple locations based on audience
- Knowledge gets extracted for agent learning
- Each repository gets its own PR (never mix repos in one commit)

---

## The Problem This Solves

**Before this pattern**:
- All work stayed in project sandbox
- Documentation duplicated across repos
- Agents couldn't find patterns from completed projects
- READMEs became novels (500+ lines)
- Maintenance nightmare (update docs in 3 places)

**After this pattern**:
- Clear separation of concerns
- Zero duplication (single source of truth per topic)
- Agents discover knowledge via three-tier system
- Lightweight READMEs (< 200 lines)
- Update once, links work everywhere

---

## Three-Tier Documentation Architecture

### Tier 1: Repository README (Lightweight)
**Location**: `<repo>/README.md` (e.g., `react-customer-dashboard/README.md`)
**Purpose**: Get developers productive FAST
**Size**: < 200 lines
**Contains**:
- App purpose (2-3 sentences)
- Quick start (npm install, npm run dev)
- Technology stack (bullet list)
- Architecture overview (1 paragraph + link to Tier 2)
- Deployment quick reference (commands + link to Tier 2)
- Troubleshooting (quick fixes + link to Tier 2)

**Audience**: Human developers, AI agents doing code-level work IN that repo

**Template**:
```markdown
# App Name

One-sentence purpose.

**Production**: https://...

## Quick Start
npm install && npm run dev

## What This App Does
- Key feature 1
- Key feature 2

## Technology Stack
- Frontend: React + TypeScript
- Backend: FastAPI
- Auth: ALB OIDC

## Architecture
Brief summary (1 paragraph)

📚 For complete architecture, deployment, operations:
→ See knowledge/applications/<app-name>/ in da-agent-hub

## Deployment
Quick commands

📚 For deployment runbook:
→ See knowledge/applications/<app-name>/deployment/ in da-agent-hub
```

### Tier 2: Knowledge Base (Comprehensive)
**Location**: `knowledge/applications/<app-name>/`
**Purpose**: Complete source of truth for architecture/deployment/operations
**Size**: Unlimited
**Structure**:
```
<app-name>/
├── README.md (comprehensive overview)
├── architecture/
│   ├── system-design.md (full architecture, diagrams)
│   ├── authentication-flow.md (auth details)
│   └── data-sources.md (integrations)
├── deployment/
│   ├── production-deploy.md (complete runbook)
│   ├── docker-build.md (container details)
│   └── rollback-procedures.md
└── operations/
    ├── monitoring.md (CloudWatch, health checks)
    ├── troubleshooting.md (comprehensive guide)
    └── incident-response.md
```

**Audience**: AI agents coordinating deployments, operations, cross-system work

**Maintenance**: Update when architecture or infrastructure changes

### Tier 3: Agent Pattern Index (Pointers)
**Location**: `.claude/agents/specialists/<agent>.md`
**Purpose**: Help agents quickly find proven patterns
**Size**: Pattern name + confidence + link (not full content)

**Format**:
```markdown
## Production-Validated Architecture Patterns

### ALB OIDC Authentication Pattern (Confidence: 0.92)
**Production Status**: ✅ Validated (app-portal + customer-dashboard)
**Reference**: `knowledge/applications/app-portal/architecture/alb-oidc-authentication.md`
**When to use**: React apps requiring Azure AD SSO
```

**Audience**: AI agents deciding what pattern to apply

**Also Update**:
- Role agents (e.g., frontend-developer-role.md) with "Known Applications" section
- Points agents to knowledge base for comprehensive docs

---

## Separation by Repository: The Critical Rule

**NEVER mix repository changes in one PR or commit**.

When completing a project that touches multiple repos:

### Step 1: Identify What Goes Where

**da-agent-hub** (Platform Knowledge):
- `.claude/agents/` - Agent pattern updates
- `knowledge/applications/` - Comprehensive app docs
- `CLAUDE.md` - Pattern documentation
- `.gitignore` - Config updates

**Production App Repos** (react-customer-dashboard, da-app-portal, etc.):
- `README.md` - Lightweight Tier 1 docs ONLY
- NO architecture/deployment details (link to knowledge base)

**Never Put in Sandbox**:
- Production code doesn't stay in `projects/active/`
- Project sandbox is for COORDINATION, not final destination

### Step 2: Create Independent PRs

**PR 1: da-agent-hub** (Knowledge Base + Agent Updates)
```bash
cd da-agent-hub
git checkout main
git pull origin main
git checkout -b feat/knowledge-base-<app-name>

# Add only da-agent-hub changes
git add knowledge/applications/ .claude/agents/ CLAUDE.md .gitignore
git commit -m "feat: Add <app-name> to knowledge base with three-tier docs"
git push -u origin feat/knowledge-base-<app-name>
gh pr create
```

**PR 2: react-<app-name>** (Lightweight README)
```bash
cd react-<app-name>
git checkout main  # or appropriate base branch
git pull origin main
git checkout -b docs/update-readme-with-knowledge-base-links

# Add ONLY README.md
git add README.md
git commit -m "docs: Update README with three-tier pattern"
git push -u origin docs/update-readme-with-knowledge-base-links
gh pr create --base main
```

**PR 3: da-app-portal** (if applicable)
```bash
# Same pattern as PR 2
```

### Step 3: Archive Project Sandbox

```bash
cd da-agent-hub
git checkout main
mkdir -p projects/completed
mv projects/active/<project-name> projects/completed/
git add projects/
git commit -m "chore: Archive completed <project-name>"
```

---

## Knowledge Extraction Checklist

When completing a project with production deployment:

### da-agent-hub Updates
- [ ] Create `knowledge/applications/<app-name>/` structure
- [ ] Write `architecture/system-design.md` (comprehensive)
- [ ] Write `deployment/production-deploy.md` (complete runbook)
- [ ] Write `operations/troubleshooting.md` (common issues)
- [ ] Update `knowledge/applications/README.md` (add app to index)
- [ ] Update specialist agent (e.g., `aws-expert.md`) with patterns + confidence scores
- [ ] Update role agent (e.g., `frontend-developer-role.md`) "Known Applications" section
- [ ] Update `CLAUDE.md` if pattern is novel
- [ ] Update `.gitignore` if new knowledge directory added

### Production Repo Updates
- [ ] Create lightweight README (< 200 lines)
- [ ] Include quick start for local dev
- [ ] Link to knowledge base for comprehensive docs
- [ ] Remove duplicated architecture/deployment details
- [ ] Keep troubleshooting quick fixes (link for comprehensive)

### Project Archival
- [ ] Move `projects/active/<name>` to `projects/completed/`
- [ ] Commit archival to da-agent-hub main branch
- [ ] Document where knowledge was extracted (commit message)

---

## Anti-Patterns to Avoid

❌ **Mixing repos in one PR**
```bash
# WRONG - This mixes da-agent-hub and react-app changes
git add knowledge/ ../react-app/README.md
git commit -m "Update everything"
```

✅ **Separate PRs per repo**
```bash
# CORRECT - Independent PRs
# PR 1: da-agent-hub (knowledge base)
# PR 2: react-app (README only)
```

❌ **Duplicating comprehensive docs**
```bash
# WRONG - Same architecture diagram in both places
react-app/README.md: [full architecture diagram]
knowledge/applications/app/architecture/: [same diagram]
```

✅ **Link instead of duplicate**
```bash
# CORRECT - Diagram lives once, README links to it
react-app/README.md: "See knowledge/applications/... for architecture"
knowledge/applications/app/architecture/: [full diagram]
```

❌ **Keeping work in sandbox**
```bash
# WRONG - Completed work stays in projects/active/
projects/active/feature-app/production-code.ts
```

✅ **Deploy to proper repos**
```bash
# CORRECT - Code goes to production repo
react-app/src/production-code.ts
projects/completed/feature-app/ (just coordination docs)
```

---

## Example: feature-salesjournaltoreact Completion

### What We Had (Sandbox):
```
projects/active/feature-salesjournaltoreact/
├── working/ (deployment experiments)
├── tasks/ (agent coordination)
├── RESUME_POINT_*.md (session notes)
└── context.md (working state)
```

### What We Created (Distributed):

**PR #96: da-agent-hub** (`feat/knowledge-base-three-tier-docs`)
- `knowledge/applications/app-portal/` (architecture, deployment, operations)
- `knowledge/applications/customer-dashboard/` (architecture, deployment, operations)
- `.claude/agents/specialists/aws-expert.md` (ALB OIDC 0.92, ECS 0.88)
- `.claude/agents/roles/frontend-developer-role.md` (Known Applications)
- `CLAUDE.md` (three-tier pattern docs)
- `.gitignore` (allow knowledge/applications/**)

**PR #3: da-app-portal** (`docs/update-readme-with-knowledge-base-links`)
- `README.md` (lightweight, links to knowledge base)

**PR: react-customer-dashboard** (`docs/update-readme-with-knowledge-base-links`)
- `README.md` (lightweight, links to knowledge base)

**Commit: da-agent-hub main**
- `projects/completed/feature-salesjournaltoreact/` (archived sandbox)

### Result:
- ✅ Production repos have lightweight READMEs
- ✅ Knowledge base has comprehensive docs (zero duplication)
- ✅ Agents know how to find information (Known Applications)
- ✅ Patterns indexed with confidence scores
- ✅ Sandbox archived (git history preserved)

---

## Benefits

**For Developers**:
- Quick start from repo README
- Links to comprehensive docs when needed
- No information overload

**For AI Agents**:
- Clear discovery path (role → knowledge base → specialist)
- Task-aware documentation (read what you need)
- Production-validated patterns with confidence scores

**For Maintenance**:
- Update once in knowledge base
- Links from READMEs don't break
- No duplicated content to keep in sync

---

## Related Patterns

- **Git Workflow**: `.claude/rules/git-workflow-patterns.md`
- **Cross-System Analysis**: `.claude/skills/reference-knowledge/cross-system-analysis-patterns/SKILL.md`
- **Testing Patterns**: `.claude/skills/reference-knowledge/testing-patterns/SKILL.md`

---

**Pattern Status**: ✅ Production-Validated
**Success Rate**: 100% (1 project: feature-salesjournaltoreact)
**Confidence**: 0.95 (proven effective, clear benefits)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/dylpickledev) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->