# Contributing to InvestSkill

Thank you for your interest in contributing! We welcome contributions of all kinds—bug reports, feature requests, documentation, and code improvements.

# Code of Conduct

Be respectful, inclusive, and professional. We’re building a community for investment research enthusiasts and professionals.

---

# Ways to Contribute

# 1. 🐛 Report Bugs

Found an issue? Help us fix it.

Open a Bug Report →

Include:

• Platform (Claude Code, Cursor, Gemini CLI, etc.)
• Your version: npm test shows version
• Steps to reproduce
• Expected vs. actual behavior
• Error messages (full output)

# 2. 💡 Suggest Features

Have an idea for a new skill or improvement?

Start a Discussion →

Describe:

• Feature overview
• Use case example
• Why it helps users
• Implementation ideas (optional)

# 3. 📚 Improve Documentation

Documentation improvements are always welcome:

• Typo fixes
• Clearer examples
• Better organization
• Updated screenshots

Improvements to:

• README files
• Inline code comments
• Guides and tutorials
• FAQs

# 4. 🎯 Add a New Skill

Want to create a new analysis framework?

See ADDING-NEW-SKILLS.md for:

• Complete 12-step walkthrough
• File structure & templates
• Platform sync checklist
• Testing procedures
• Review process

# 5. 🧪 Fix Bugs

Found and fixed a bug? We’d love your PR!

# 6. ✨ Enhance Existing Skills

Improvements to existing frameworks:

• Better algorithms
• More comprehensive analysis
• Faster computation
• Better documentation

---

# Development Setup

# Prerequisites

• Node.js 18.0.0+
• git
• GitHub account

# Local Setup

# Clone repository
git clone https://github.com/yennanliu/InvestSkill.git
cd InvestSkill

# Install dependencies (if any)
npm install

# Run test suite
npm test

# Run validation
npm run pre-release

# Verify setup
npm run verify

# Test Before Submitting

# All checks
npm run pre-release

# Or individually
npm test                          # Unit tests
npm run validate                  # Prompt quality
npm run verify                    # Setup verification
npm run integration-tests         # Platform artifacts

All tests must pass before submitting a PR.

---

# Submitting Changes

# Before You Start

1. Check if your idea is already discussed in Issues or Discussions
2. For new skills: read ADDING-NEW-SKILLS.md
3. For bugs: confirm it’s reproducible locally

# Creating a Pull Request

1. Fork the repository

   git clone https://github.com/YOUR-USERNAME/InvestSkill.git
   cd InvestSkill
   

2. Create a feature branch

   git checkout -b feature/your-feature-name
   # or: git checkout -b fix/issue-name
   

3. Make your changes

   • Keep commits focused (one feature/fix per commit)
   • Write clear commit messages
   • Reference issues: fixes #123

4. Test your changes

   npm test                    # Unit tests
   npm run integration-tests   # Platform tests
   npm run pre-release         # Full validation
   

5. Push to your fork

   git push origin feature/your-feature-name
   

6. Open a Pull Request

   • Reference the issue being fixed: fixes #123
   • Describe what your change does
   • Explain why it’s needed
   • Include test results (screenshots, output, etc.)

# PR Checklist

• [ ] Tests pass: npm test shows 270+ passed
• [ ] Linting passes: No warnings
• [ ] Documentation updated
• [ ] Commit messages are clear
• [ ] Changes follow project conventions
• [ ] Added new tests if needed

---

# Code Standards

# Naming Conventions

• Files: kebab-case (stock-eval.md)
• Functions: camelCase (getStockMetrics())
• Constants: UPPER_SNAKE_CASE (MAX_RETRIES)
• Classes: PascalCase (StockAnalyzer)

# JavaScript Style

• Use 'use strict' at top of files
• 2-space indentation
• Semicolons required
• No trailing commas in objects

# Markdown Style

• 80-character line limit
• Clear section headers (# Main, ## Sub, ### Detail)
• Code blocks with language tags
• Tables for structured data
• Links in markdown: [text](url)

# Comments

• Code comments: Why, not what

  // Filter out delisted tickers (removed from exchanges)
  const activeTickers = tickers.filter(t => !delistedSet.has(t));
  

• Documentation: Clear, concise, complete

  ### Feature Name
  Brief description. Key benefits. Use case.
  

---

# Adding a New Skill

See ADDING-NEW-SKILLS.md for the comprehensive guide.

Quick summary:

1. Create skill directory: plugins/us-stock-analysis/skills/skill-name/
2. Write SKILL.md (Claude Code skill definition)
3. Copy to prompts/skill-name.md (universal prompt, no frontmatter)
4. Register in plugin.json
5. Update .cursor/rules/, GEMINI.md, .github/copilot-instructions.md
6. Update README files & CHANGELOG
7. Run full test suite
8. Submit PR with all changes

---

# Review Process

# What We Look For

✅ Good PRs have:

• Clear purpose & description
• Tests passing (270+ unit tests, 22 integration tests)
• Updated documentation
• Focused, logical commits
• Follows project conventions

❌ Issues that delay approval:

• Tests failing
• Documentation not updated
• Unclear commit messages
• Style inconsistencies
• Too many unrelated changes

# Timeline

• Small fixes: 1-3 days
• New skills: 3-7 days
• Major changes: 1-2 weeks

Reviewers will provide feedback, or approve and merge.

---

# Questions?

• How do I add a new skill? → ADDING-NEW-SKILLS.md
• I’m stuck. → GitHub Discussions
• Found a bug. → GitHub Issues
• Need help? → FAQ.md

---

# Resources

Resource	Purpose
README.md	Project overview
ADDING-NEW-SKILLS.md	Complete contributor guide
FAQ.md	Common questions & answers
CHANGELOG.md	Version history
DEPLOYMENT-STATUS.md	Current platform status

---