Skip to content

Commit 01277a4

Browse files
nirukk52nirukk52
authored
Chore refactor documentation (#24)
* docs: refactor README, CLAUDE, and documentation hierarchy - Refactor README.md to 358 lines (surgical, external-facing) - Update CLAUDE.md with README.md section in documentation hierarchy - Update WHAT_WE_ARE_MAKING.md to align with new platform description - Add document maintenance rules in CLAUDE.md - Ensure alignment across README, CLAUDE, and founder_rules.mdc - Clean up deprecated documentation files - Update spec folders structure * feat: add dev-log-monitoring skill and skill decision guide - Created dev-log-monitoring_skill for live log monitoring during manual testing - Added comprehensive SKILL_DECISION_GUIDE.md comparing all 6 skills - Skill provides 6-step workflow: start services, navigate with Playwright MCP, monitor logs, analyze flow, generate report, cleanup - Includes log patterns reference for backend (Encore.ts) and frontend (SvelteKit) - Fixed artifacts service get-content.ts type issue
1 parent 7b244e2 commit 01277a4

35 files changed

+1019
-543
lines changed

‎.claude-skills/SKILL_DECISION_GUIDE.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# ScreenGraph Skills: Decision Guide
2+
3+
## 🎯 Quick Reference: Which Skill Should I Use?
4+
5+
### I'm building something...
6+
- **Backend feature** → `backend-development_skill`
7+
- **Frontend feature** → `frontend-development_skill`
8+
9+
### Something broke...
10+
- **Backend test failed** → `backend-debugging_skill`
11+
- **UI is broken** → `frontend-debugging_skill`
12+
13+
### I'm testing...
14+
- **Manual testing + watching logs** → `dev-log-monitoring_skill`
15+
- **Automated regression testing** → `e2e-testing_skill`
16+
17+
---
18+
19+
## 📊 Skill Comparison Matrix
20+
21+
| Skill | Primary Purpose | When Active | Output | Tools Used |
22+
|-------|----------------|-------------|---------|------------|
23+
| **dev-log-monitoring** | Live monitoring + post-run analysis | During manual testing | Log analysis report | Playwright MCP, grep, tail |
24+
| **e2e-testing** | Automated regression testing | Pre-push, CI/CD | Pass/fail + artifacts | Playwright automated |
25+
| **backend-debugging** | Fix failing tests/services | When tests fail | Root cause + fix | SQL queries, diagnostic scripts |
26+
| **backend-development** | Build new backend features | During development | Working code + tests | Encore.ts, integration tests |
27+
| **frontend-debugging** | Fix UI/component issues | When UI breaks | Root cause + fix | Browser DevTools, type checking |
28+
| **frontend-development** | Build new UI features | During development | Working components | Svelte 5, Skeleton UI |
29+
30+
---
31+
32+
## 🔄 Common Workflows
33+
34+
### Workflow A: Building New Backend Feature
35+
```
36+
1. backend-development_skill (build + write tests)
37+
↓
38+
2. If tests fail → backend-debugging_skill
39+
↓
40+
3. Before commit → e2e-testing_skill (verify no regressions)
41+
```
42+
43+
### Workflow B: Building New Frontend Feature
44+
```
45+
1. frontend-development_skill (build UI)
46+
↓
47+
2. If UI breaks → frontend-debugging_skill
48+
↓
49+
3. Manual verification → dev-log-monitoring_skill (watch full flow)
50+
↓
51+
4. Before commit → e2e-testing_skill (automated validation)
52+
```
53+
54+
### Workflow C: Investigating Production Issue
55+
```
56+
1. dev-log-monitoring_skill (reproduce + capture logs)
57+
↓
58+
2a. If backend issue → backend-debugging_skill
59+
2b. If frontend issue → frontend-debugging_skill
60+
↓
61+
3. Write regression test → e2e-testing_skill
62+
```
63+
64+
### Workflow D: Pre-Release Verification
65+
```
66+
1. e2e-testing_skill (run full suite)
67+
↓
68+
2. If failures → specific debugging skill
69+
↓
70+
3. Manual smoke test → dev-log-monitoring_skill (watch key flows)
71+
```
72+
73+
---
74+
75+
## ✅ Why We Need All 6 Skills
76+
77+
**dev-log-monitoring_skill** ✅
78+
- **Unique:** Only skill for live log monitoring during manual testing
79+
- **No Overlap:** All others are automated or focus on different phases
80+
81+
**e2e-testing_skill** ✅
82+
- **Unique:** Only automated Playwright testing skill
83+
- **No Overlap:** Automation vs manual exploration
84+
85+
**backend-debugging_skill** ✅
86+
- **Unique:** SQL queries, diagnostic scripts, structured log analysis
87+
- **No Overlap:** Diagnosis, not development
88+
89+
**backend-development_skill** ✅
90+
- **Unique:** Integration test patterns, polling helpers
91+
- **No Overlap:** Building, not debugging
92+
93+
**frontend-debugging_skill** ✅
94+
- **Unique:** 10-phase systematic Svelte/runes debugging
95+
- **No Overlap:** Diagnosis, not development
96+
97+
**frontend-development_skill** ✅
98+
- **Unique:** Svelte 5 runes + Skeleton UI patterns
99+
- **No Overlap:** Building, not debugging
100+
101+
---
102+
103+
## 🎓 Visual Decision Tree
104+
105+
```
106+
"I want to..."
107+
│
108+
├─── BUILD something?
109+
│ ├─── Backend? → backend-development_skill
110+
│ └─── Frontend? → frontend-development_skill
111+
│
112+
├─── DEBUG something?
113+
│ ├─── Backend test failed? → backend-debugging_skill
114+
│ ├─── Frontend/UI broken? → frontend-debugging_skill
115+
│ └─── E2E test failed? → e2e-testing_skill (then escalate)
116+
│
117+
└─── TEST something?
118+
├─── Manual + watch logs? → dev-log-monitoring_skill
119+
└─── Automated regression? → e2e-testing_skill
120+
```
121+
122+
---
123+
124+
## 💡 Pro Tips
125+
126+
1. **Start with development skill, escalate to debugging skill**
127+
- Don't jump to debugging without trying development patterns first
128+
129+
2. **dev-log-monitoring is for MANUAL exploration**
130+
- Use when you want to understand system behavior
131+
- Not for CI/CD (use e2e-testing for that)
132+
133+
3. **e2e-testing catches regressions, debugging skills find root causes**
134+
- E2E tells you WHAT broke
135+
- Debugging skills tell you WHY it broke
136+
137+
4. **All 6 skills are complementary, not redundant**
138+
- Each fills a specific gap in the development lifecycle
139+

‎.claude-skills/after-task_skill/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,3 +290,4 @@ From `founder_rules.mdc`:
290290

291291
**Purpose**: Capture institutional knowledge so future work benefits from past work. The self-improvement loop closes here.
292292

293+

‎.claude-skills/before-task_skill/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,3 +152,4 @@ git checkout -b bug-[description]
152152

153153
**Purpose**: Load comprehensive context ONCE at the start. Everything else builds from this foundation.
154154

155+

‎.claude-skills/code-review_skill/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,3 +167,4 @@ Update this skill when:
167167
**Version:** 1.0
168168
**Maintainer:** Founder
169169

170+

‎.claude-skills/code-review_skill/assets/review-template.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,4 @@
7373

7474
**Recommended Action:** [Approve / Request Changes / Needs Discussion]
7575

76+

‎.claude-skills/code-review_skill/references/review-guidelines.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,3 +315,4 @@ This skill should evolve based on:
315315

316316
Update this reference document when new patterns emerge or guidelines change.
317317

318+

0 commit comments

Comments
 (0)