gh-levnikolaevich-claude-code-skills-full-development-workflow-skills/skills/ln-114-project-docs-creator/references/guides/automatic_analysis_guide.md

Automatic Analysis Guide

Guide for automatic analysis of project materials and researching 2025 best practices.

---

Section 1: Analyzing Project Materials

When to Analyze

Ask user: "Do you have project materials to analyze? (files, diagrams, docs, code)"

Files to Search (use Glob + Read)

Package managers: package.json, requirements.txt, go.mod, pom.xml, Gemfile Docker: Dockerfile, docker-compose.yml, docker-compose.test.yml Config: tsconfig.json, *.env.example, .nvmrc Docs: README.md, architecture diagrams Code structure: src/, api/, services/, tests/

Information to Extract

From package.json / requirements.txt / go.mod:

• Runtime version (Node 18, Python 3.11, Go 1.21)
• Dependencies → frameworks, databases, auth, cache
• Pre-populate: Q9, Q12

From Dockerfile:

• Base image → runtime version
• Multi-stage structure → build optimization
• Pre-populate: Q9, Q12

From docker-compose.yml:

• Services → app + db + cache + queue
• Images → database/cache versions
• Volumes → hot-reload setup
• Pre-populate: Q9, Q11

From docker-compose.test.yml:

• Test services → db-test, cache-test (isolated)
• Volumes → ./src, ./tests (hot-reload)
• Tmpfs → in-memory test databases
• Command → test framework
• Pre-populate: Q12 (test setup)

Output Format

✓ Analyzed project materials

**Detected**:
- Runtime: [runtime + version]
- Framework: [framework + version]
- Database: [database]
- Architecture: [hints from docker-compose]

**Pre-populated**: Q9, Q12 (partial)

---

Section 2: Researching Best Practices 2025

When to Research

During Phase 2, Stage 2 for questions Q9, Q11-Q13.

Ask user first: "Research best practices automatically? (Y/N)"

Research Tools

MCP Ref (mcp__Ref__ref_search_documentation):

• Query: "[framework] latest version 2025"
• Use for: Official docs, version numbers, features
• Then Read: mcp__Ref__ref_read_url for details

WebSearch:

• Query patterns:
  • "[Tech A] vs [Tech B] 2025 comparison"
  • "best practices [technology] 2025"
  • "[pattern] architecture pros cons 2025"
• Use for: Comparisons, best practices, trends

Research Strategy by Question

Q9: Technology Decisions

1. Check analyzed versions vs 2025 latest
2. MCP Ref: latest stable versions
3. WebSearch: security vulnerabilities, release notes
4. Recommend upgrades if: EOL, security issues, LTS available

Q11: Architectural Patterns

1. Identify project type + scale from Stage 1
2. WebSearch: "[project type] architecture patterns 2025"
3. Consider scale:
   • Small (< 10K users) → Monolith
   • Medium (10K-100K) → Microservices
   • Large (100K+) → Microservices + Event-Driven

Q12: Libraries and Frameworks

1. Based on Q9 + Q11
2. MCP Ref: latest versions for each component
3. WebSearch: compatibility, comparisons
4. Check: ORM, testing framework, validation library
5. Verify compatibility matrix

Q13: Integrations

1. Identify needs from Q5 (IN SCOPE)
2. WebSearch comparisons:
   • Payments: "Stripe vs PayPal 2025"
   • Email: "SendGrid vs AWS SES 2025"
   • Auth: "Auth0 vs Clerk 2025"
   • Storage: "AWS S3 vs Cloudinary 2025"
3. Consider: pricing, DX, compliance, popularity

Dockerfile Generation

Based on Q12 runtime + framework:

• Latest stable base image
• Multi-stage build (dev + prod)
• Security: non-root user, minimal image
• Generate docker-compose.yml with services from Q11

---

Section 3: Transition to Interactive Mode

When to Ask User

Pause research when:

1. Multiple alternatives (React vs Vue) → present both, ask preference
2. Insufficient info (no files found) → ask directly
3. Unclear goals (vague Q5) → ask clarifying questions
4. Always interactive: Q10, Q14-Q19 (org-specific)

Alternative Presentation Template

"Researched [Category]:

**Option A**: [Tech A]
Pros: [key benefits]
Cons: [key drawbacks]

**Option B**: [Tech B]
Pros: [key benefits]
Cons: [key drawbacks]

Recommendation: [A/B] because [reason]

Which do you prefer? (A/B/Other)"

Fallback to Full Interactive

If no materials OR user declines research → ask all Q9-Q19 interactively

---

Section 4: Quality Guidelines

Verification Checklist

• Version is 2025-current (< 1 year old)
• Stable release (not beta)
• No critical security vulnerabilities
• Compatible with other tech
• Active community (GitHub stars, updates)
• Official docs available

Red Flags (Don't Recommend)

• Last updated > 2 years ago
• Unpatched security vulnerabilities
• Incompatible with stack
• Beta/experimental (unless requested)
• Obscure (<1000 GitHub stars)

Rationale Format

Recommendation: [Technology]
Rationale:
1. [Technical reason]
2. [Ecosystem reason]
3. [Project fit reason]
4. [Industry adoption]

---

Section 5: Execution Flow

Phase 1.5: Material Analysis

User provides materials? (Y/N)
├─ Y: Glob + Read files → Extract info → Report findings
└─ N: Skip to Phase 2

Phase 2, Stage 2: Research & Design

Stage 1 complete (Q1-Q8 answered)
  ↓
Research automatically? (Y/N)
├─ Y: Research Q9, Q11-Q13 → Present recommendations → User accepts/modifies
└─ N: Ask Q9-Q13 interactively
  ↓
Always ask Q10, Q14-Q19 interactively

---

Version: 1.0.0 Last Updated: 2025-10-29