Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
450 lines (344 loc) · 11.4 KB

CONTRIBUTING.md

File metadata and controls

450 lines (344 loc) · 11.4 KB
Raw

Contributing to EssayMaster

Thank you for your interest in contributing to EssayMaster! This document provides guidelines and information for contributors.

Code of Conduct

Our Commitment

We are committed to:

  • Helping students find their authentic voice - Never ghostwriting or providing pre-written content
  • Respecting student privacy and ownership - All work belongs to the student
  • Maintaining high ethical standards - Following admissions counseling best practices
  • Supporting honest self-representation - No plagiarism or misrepresentation

Our Standards

Positive Behaviors:

  • Using welcoming and inclusive language
  • Respecting differing viewpoints and experiences
  • Accepting constructive criticism gracefully
  • Focusing on what's best for students
  • Showing empathy toward other contributors

Unacceptable Behaviors:

  • Sharing student work without explicit permission
  • Providing generic templates that undermine authenticity
  • Encouraging dishonesty or misrepresentation
  • Supporting plagiarism in any form
  • Harassment, trolling, or insulting comments

How to Contribute

Reporting Issues

Found a bug or have a suggestion? Open an issue

Before opening an issue:

  1. Search existing issues to avoid duplicates
  2. Use issue templates when available
  3. Provide clear description of the problem or suggestion
  4. Include context: Which phase does this relate to?
  5. Share examples: Anonymized examples if possible

Issue Categories:

  • 🐛 Bug Report - Something isn't working correctly
  • ✨ Feature Request - New functionality or improvement
  • 📚 Documentation - Improvements to docs or examples
  • ❓ Question - General questions about usage
  • 💡 Discussion - Ideas for consideration

Suggesting Improvements

We welcome suggestions! Good contributions include:

Question Library:

  • Additional coaching questions for Phase 1
  • Follow-up question patterns
  • Questions for specific situations (ESL students, transfer students, etc.)

Writing Techniques:

  • New introduction strategies beyond the current 4
  • Conclusion approaches
  • Transition techniques
  • Voice preservation methods

Editing Frameworks:

  • Additional editing checklists
  • Common error patterns (especially ESL)
  • Before/after examples (anonymized)

Examples:

  • Anonymous essay samples showing technique
  • Source document examples
  • Outline examples for different themes

Tool Integrations:

  • Integration with other Claude skills
  • MCP server connections
  • Writing tools compatibility

Process Improvements:

  • Efficiency enhancements
  • Better session state management
  • Collaborative workflows

Pull Requests

Before Submitting a PR

  1. Discuss major changes - Open an issue first for significant changes
  2. Check existing PRs - Avoid duplicate work
  3. Test thoroughly - Ensure your changes work as expected
  4. Update documentation - Keep docs in sync with code changes

PR Process

  1. Fork the repository

    git clone https://github.com/YOUR_USERNAME/Essaymaster.git
cd Essaymaster

  2. Create a feature branch

    git checkout -b feature/descriptive-name

    Branch naming conventions:

    • feature/ - New features
    • fix/ - Bug fixes
    • docs/ - Documentation updates
    • refactor/ - Code improvements

  3. Make your changes

    • Follow existing formatting and style
    • Add comments for complex logic
    • Update YAML templates if needed

  4. Test your changes

    • Test with Claude Code
    • Verify all phases still work
    • Check documentation renders correctly

  5. Commit with clear messages

    git add .
git commit -m "feat: Add new coaching questions for STEM students"

    Commit message format:

    • feat: - New feature
    • fix: - Bug fix
    • docs: - Documentation changes
    • refactor: - Code refactoring
    • test: - Test additions/changes

  6. Push to your fork

    git push origin feature/descriptive-name

  7. Open a Pull Request

    • Use the PR template
    • Reference related issues
    • Explain the benefit clearly
    • Add screenshots/examples if applicable

PR Guidelines

Good PRs:

  • ✅ One feature/fix per PR (focused scope)
  • ✅ Clear description of changes and why
  • ✅ Updated documentation if needed
  • ✅ Follows existing code style
  • ✅ Includes examples or tests
  • ✅ References related issues

Avoid:

  • ❌ Multiple unrelated changes in one PR
  • ❌ Breaking changes without discussion
  • ❌ Undocumented new features
  • ❌ Student work or private information
  • ❌ Changing code style without purpose

Documentation Contributions

Documentation is crucial! We welcome:

README improvements:

  • Clearer explanations
  • Additional examples
  • Better organization
  • Grammar/spelling fixes

New guides:

  • Phase-specific deep dives
  • Tool integration tutorials
  • Troubleshooting guides
  • Best practices

Example collection:

  • Anonymized essay samples
  • Source document examples
  • Before/after editing samples
  • Common mistake patterns

Translation:

  • Translate documentation to other languages
  • Add ESL-specific guidance
  • Cultural adaptation notes

Development Guidelines

Skill File Structure

When modifying college-essay-coach.md:

Maintain these sections:

  1. When to Use This Skill - Clear scope definition
  2. Skill Philosophy - Core principles
  3. The 4-Phase Process - Complete workflow
  4. Phase Details - Each phase thoroughly documented
  5. Reference Materials - Checklists, examples, templates
  6. Technical Integration - Tool usage guides

Formatting conventions:

  • Use H2 (##) for major sections
  • Use H3 (###) for subsections
  • Use H4 (####) for detailed breakdowns
  • Code blocks for YAML templates
  • Quote blocks for examples
  • Bullet lists for checklists

YAML Template Standards

Required fields:

# Source Documents
story_id: [descriptive-slug]
category: [identity/experience/reflection/academic/emotional]
title: "[Brief Descriptive Title]"
prompt: "[Question that elicited this]"
date_created: [YYYY-MM-DD]
keywords: [tag1, tag2, tag3]
content: ...
connections: ...
potential_themes: ...

# Outlines
concept: [Key Theme]
working_title: "[Title]"
target_word_count: 650
source_stories: [story_ids]
introduction: ...
body: ...
conclusion: ...
traits_revealed: ...
uniqueness_factor: ...
student_approved: [yes/no]

Best practices:

  • Use descriptive story_ids (e.g., coffee-shop-grandmother not story1)
  • Include all sensory details where applicable
  • Keep keywords specific and meaningful
  • Always note connections between documents

Question Design Principles

When adding coaching questions:

Good questions:

  • ✅ Open-ended (can't answer with yes/no)
  • ✅ Specific and concrete (not vague)
  • ✅ Encourage storytelling (not summarizing)
  • ✅ Seek surprising details (not expected answers)
  • ✅ Focus on actions (not just thoughts/feelings)

Examples:

Good:

"Walk me through what happened. What's the first thing you remember seeing?"

Not ideal:

"Did you have a good experience?" (yes/no, vague)

Good:

"What did you DO when you realized this? What specific actions did you take?"

Not ideal:

"How did that make you feel?" (tells, doesn't show)

Voice Preservation Guidelines

When editing examples or creating new content:

Principles:

  1. Authentic > Polished - Keep student voice even if informal
  2. Specific > Generic - "Chocolate-chip cookie" not "dessert"
  3. Active > Passive - "I opened" not "was opened by me"
  4. Show > Tell - Actions/details not feeling-labels

Red flags:

  • Vocabulary too sophisticated for natural speech
  • All sentences same length/structure
  • Personality smoothed out
  • Humor or quirks removed

Testing

Manual Testing Checklist

Before submitting changes, test:

Phase 1:

  • All question prompts work in conversation
  • YAML documents generate correctly
  • Follow-up questions flow naturally

Phase 2:

  • Concept extraction logic is sound
  • Outline templates complete
  • Student interaction points clear

Phase 3:

  • Writing guidance is actionable
  • Fatal flaws check catches issues
  • Voice preservation emphasized

Phase 4:

  • All 5 editing levels function
  • Checklist items are verifiable
  • Tool integrations work

General:

  • Session state management works
  • Navigation between phases clear
  • Documentation accurate

Style Guide

Writing Style

Tone:

  • Warm and encouraging (coach, not critic)
  • Clear and direct (no jargon unless explained)
  • Respectful of student agency
  • Supportive but honest

Language:

  • Use "you" to address students
  • Use "we" for collaborative work
  • Avoid passive voice
  • Keep sentences concise

Examples:

  • ✅ "Let's explore this story together"
  • ❌ "The story should be explored"
  • ✅ "What surprised you about this moment?"
  • ❌ "Ascertain the elements of unexpectedness"

Code Style

YAML:

# Use descriptive keys
story_id: grandmother-coffee-shop  # ✅
story_id: story1                    # ❌

# Include context in comments
# This captures the moment of learning precision
moment: |
  ...

Markdown:

## Use Clear Headings

**Bold** for emphasis, not _italics_

`Code` for specific terms or commands

> Quotes for examples or student voices

Review Process

What to Expect

  1. Initial Review - Maintainer checks PR against guidelines
  2. Feedback - Suggestions for improvements if needed
  3. Discussion - Collaborative refinement
  4. Approval - PR merged when ready
  5. Recognition - Added to contributors list

Review Criteria

We look for:

  • ✅ Aligns with skill philosophy
  • ✅ Maintains ethical standards
  • ✅ Improves student experience
  • ✅ Clear and well-documented
  • ✅ Tested and working

Common feedback:

  • Needs more examples
  • Documentation unclear
  • Missing edge cases
  • Style inconsistency
  • Breaking existing functionality

Recognition

Contributors

All contributors will be:

  • Added to the README acknowledgments
  • Listed in CONTRIBUTORS.md (if significant contribution)
  • Credited in release notes (for features)

Types of Contributions

Code contributions:

  • Skill file improvements
  • Template enhancements
  • Tool integrations

Documentation:

  • README improvements
  • New guides or tutorials
  • Example collection

Community:

  • Answering questions
  • Bug reports
  • Feature suggestions
  • Testing and feedback

Getting Help

Resources

Documentation:

Community:

Contact

  • Issues: For bugs and feature requests
  • Discussions: For questions and ideas
  • Email: [Create issue instead for better tracking]

Thank You!

Your contributions help students discover and articulate their authentic stories. Every improvement makes college essay coaching more accessible and effective.

Remember:

  • Quality over quantity
  • Student voice is paramount
  • Authenticity beats cleverness
  • We're coaches, not ghostwriters

Happy contributing! 🎓✨