discover

Discover Skill (Stage 1)

This skill analyzes existing projects and generates Gastown-compatible semantic memory.

When to Use

Use this skill when:

• Starting migration of an existing project
• Need to understand a codebase's tech stack
• Want to document project constraints and goals
• Preparing for roadmap generation (Stage 2)

Output Structure

project/
├── .gt/
│   └── memory/
│       ├── semantic.json      # Permanent facts (tech stack, constraints)
│       ├── episodic.json      # Decisions with TTL (optional)
│       └── procedural.json    # Learned patterns (optional)
└── [existing project files]

Discovery Procedure

Scan these locations in priority order:

1. Package Files (Tech Stack Detection)

File	Detects
package.json	Node.js runtime, framework, dependencies
Cargo.toml	Rust projects
go.mod	Go projects
requirements.txt	Python dependencies
pyproject.toml	Python projects (modern)
Gemfile	Ruby projects
pom.xml	Java/Maven projects
build.gradle	Java/Gradle projects

2. Configuration Files (Service Detection)

File	Detects
.firebaserc, firebase.json	Firebase
wrangler.toml	Cloudflare Workers
vercel.json	Vercel deployment
netlify.toml	Netlify deployment
docker-compose.yml	Containerization
Dockerfile	Container build
*.env.example	Environment variables
.github/workflows/	CI/CD (GitHub Actions)

3. Documentation (Project Understanding)

File	Provides
README.md	Project description, setup
docs/	Architecture docs, ADRs, PRDs
CONTRIBUTING.md	Development workflow
CHANGELOG.md	Project history
LICENSE	License type

4. Source Structure (Codebase Understanding)

Directory	Indicates
src/, lib/, app/	Main code location
tests/, __tests__/, spec/	Test location
schemas/, migrations/	Database schemas
components/	UI component library
api/, routes/	API structure

Tech Stack Extraction

Scan package and config files for dependencies, then map to canonical label names:

• Frameworks: "Next.js", "React", "Vue.js", "Angular", "Express.js", "Fastify", "Django", "Flask", "FastAPI", "Ruby on Rails", "Gin"
• Databases: "PostgreSQL", "MySQL", "MongoDB", "Redis" — include ORM if present ("Prisma", "Drizzle", "TypeORM")
• Auth: "Firebase Auth", "Auth0", "NextAuth.js", "Clerk", "Supabase Auth", "Passport.js"

Use exact names above. If a dependency doesn't match a known canonical name, use the package name as-is.

Output: semantic.json

{
  "$schema": "semantic-memory-v1",
  "project": {
    "name": "my-app",
    "type": "web-application",
    "primary_language": "TypeScript",
    "description": "A task management app for teams"
  },
  "tech_stack": {
    "runtime": "Node.js 20",
    "framework": "Next.js 14",
    "database": "Neon PostgreSQL",
    "auth": "Firebase Auth",
    "deployment": "Vercel",
    "styling": "Tailwind CSS",
    "testing": "Vitest",
    "orm": "Drizzle"
  },
  "personas": [
    {"name": "Team Lead", "needs": ["assign tasks", "track progress"]},
    {"name": "Developer", "needs": ["see my tasks", "update status"]}
  ],
  "constraints": [
    "Must support offline mode",
    "GDPR compliant data handling"
  ],
  "non_goals": [
    "Mobile native app (web-only for MVP)",
    "Enterprise SSO (future phase)"
  ],
  "evidence": {
    "last_scan": "2026-01-27T10:00:00Z",
    "files_analyzed": ["package.json", "README.md", "docs/PRD.md"]
  }
}

Memory Types

Semantic Memory (Required)

Permanent facts that don't change:

• Project name and type
• Primary programming language
• Tech stack components
• Architectural constraints
• Non-goals

Episodic Memory (Optional)

Decisions with time-to-live (~30 days):

• Architecture decisions
• Library choices with rationale
• Trade-offs made

Procedural Memory (Optional)

Learned patterns:

• Code conventions
• Testing patterns
• Deployment procedures

Quality Gates

Gate	Requirement
semantic_valid	semantic.json is valid JSON
project_identified	project.name is not null or empty
tech_stack_detected	At least 2 tech_stack fields populated
evidence_recorded	evidence.files_analyzed has 1+ entries

Validation

python plugins/lisa/hooks/validate.py --stage discover

Error Handling

If unable to detect something:

• Set field to null rather than guessing
• Add to evidence.unresolved list (if pattern exists)
• Document what was searched and why it failed

Next Steps

After discover completes:

• Proceed to Stage 2 (Plan) → skills/plan/SKILL.md
• Or proceed directly to Stage 3 (Structure) if roadmap exists