cclohmar/OpenWriterControle
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
OpenWriterControle/.opencode/context/content/tone-voice.md
Darren Hinde c8f7103cb6
refactor(evals): consolidate documentation and enhance test infrastructure (#56) 
* feat(agents): implement category-based agent organization system

- Organize agents into domain categories (core, development, content, data, product, learning)
- Move 10 agents to category subdirectories with proper git rename tracking
- Update 13 subagents with category and type metadata in frontmatter
- Add category metadata files (0-category.json) documenting common patterns
- Implement local registry fallback in install script for offline development
- Add comprehensive validation suite with 15 automated tests (100% pass rate)
- Enhance registry validation with duplicate ID and consistency checks
- Update eval framework with intelligent path resolution (backward compatible)
- Archive legacy eval structure to _archive/ for reference
- Update all documentation to reflect category-based structure
- Bump version to 0.5.0 with accurate CHANGELOG

Technical Details:
- 23 agents organized (10 category agents, 13 subagents)
- 6 category directories created
- Path resolution supports both agent IDs and category paths
- Registry schema updated to v2.0.0
- 159 files changed, 872 insertions(+), 10738 deletions(-)

BREAKING CHANGE: Agent file paths now use category structure. Update references from .opencode/agent/openagent.md to .opencode/agent/core/openagent.md. Eval framework maintains backward compatibility via path resolution.

* refactor(evals): consolidate documentation and enhance test infrastructure

- Remove temporary project tracking files (PHASE_5_COMPLETE, PROJECT_COMPLETE, etc.)
- Consolidate evaluation framework docs into main README
- Enhance test execution with improved logging and multi-prompt support
- Move system-builder from core to meta category
- Add comprehensive test suites for openagent with organized structure
- Create evaluation test structure for all subagents
- Clean up archived workflows and redundant documentation
- Update registry to reflect new agent organization
- Add shared test templates and golden test patterns

* feat(ci): add manual trigger support for bot-created PRs in validate-registry workflow

- Add pr_number input to workflow_dispatch for manually triggering validation
- Fetch PR details dynamically when triggered manually
- Support both automatic (PR event) and manual (workflow_dispatch) triggers
- Enable validation of bot-created PRs like automated version bumps
- Update branch detection and push logic to handle both trigger types
- Add documentation explaining how to manually trigger for bot PRs

* feat(evals): add explicit context file validation to test framework

- Add expectedContextFiles field to test YAML schema for explicit context file specification
- Enhance context-loading-evaluator to support both auto-detect and explicit validation modes
- Update documentation with comprehensive guide and examples
- Clean up archived legacy test structure (90+ old test files)
- Add new example tests demonstrating explicit context validation
- Backward compatible with existing tests

* feat(evals): add multi-agent logging system and performance optimizations

Implement comprehensive multi-agent logging and performance improvements for the eval framework.

Task 01: Multi-Agent Logging System
- Add complete hierarchical logging module (evals/framework/src/logging/)
  - SessionTracker: tracks parent-child delegation hierarchies
  - MultiAgentLogger: pretty-prints logs with visual indentation
  - Formatters: box characters and emoji formatting
  - 37 passing unit tests (session-tracker, logger, integration)
- Integrate with SDK event stream handler
  - Hook into session.created, message.updated, message.part.updated events
  - Real-time child session detection via timestamp heuristics
  - Message deduplication for cleaner output
- Enable in debug mode only (<1% performance overhead)
- Add demo script and comprehensive documentation

Task 02: Performance Optimizations
- Reduce grace period from 5s to 2s (67% reduction, 10-20% faster tests)
- Add PerformanceMetricsEvaluator for bottleneck identification
  - Collects tool latencies, inference time, idle time
  - Provides full performance visibility
- Update smoke test to validate delegation (core feature)
  - Replace simple read test with multi-agent delegation test
  - Tests both parent and child agent functionality
  - Validates multi-agent logging system

Results:
- 37 unit tests passing
- Smoke test passing (95/100 score)
- Clean hierarchical logging output
- 10-20% faster test execution
- Full multi-agent visibility

Files changed: 16 files, +2678 lines
Time saved: ~6-8 days (completed in 6 hours vs 3-5 day estimate)

* feat(evals): show child agent execution in non-debug mode

- Enable MultiAgentLogger in both debug and non-debug modes
- Add verbose parameter to control output level
- Non-verbose mode shows concise child session lifecycle:
  - Child agent started message
  - Child agent completed with duration
- Verbose mode (--debug) shows full delegation hierarchy
- Update documentation to reflect new behavior

This provides visibility into delegation without overwhelming output,
giving confidence that child agents are actually running.

* feat(evals): improve delegation testing and behavior validation

Major improvements to eval framework:

Test Suite:
- Add 00-smoke-test.yaml (basic read operation)
- Rename 01-smoke-test.yaml → 02-delegation-test.yaml (delegation test)
- Add simple-responder test agent for delegation testing
- Add debug test: simple-subagent-call.yaml

Evaluators:
- Add agent-model-evaluator.ts for agent/model validation
- Enhance behavior-evaluator.ts with detailed task tool output
- Improve delegation-evaluator.ts with better evidence tracking

Schema & Execution:
- Add expectedAgent and expectedModel to test schema
- Improve test executor with better logging and error handling

Documentation:
- Update evals/README.md with new features and performance improvements
- Remove outdated MULTI_AGENT_LOGGING_COMPLETE.md

Registry:
- Add simple-responder test agent to registry

Fixes:
- Fix dashboard.sh path resolution

These changes provide better visibility into delegation, improved test
coverage, and clearer validation of agent behavior.

* chore: add GitHub Actions workflow and plugin documentation

- Add .github/workflows/evals/run-evaluations.yml for automated eval testing
- Add dev/ai-tools/opencode/plugins/Plugin-inspiration.md for plugin development reference
2025-12-18 09:52:11 +00:00

7.3 KiB
Raw Blame History

Tone & Voice Guidelines

Category: content
Purpose: Maintaining consistent brand voice and adapting tone for different contexts
Used by: copywriter, technical-writer

Overview

Voice is your brand's personality - it stays consistent. Tone is how that voice adapts to different situations and audiences. This guide helps maintain consistency while being contextually appropriate.

Voice vs. Tone

Voice (Consistent)

Your brand's personality that never changes:

  • Professional but approachable
  • Knowledgeable but not condescending
  • Confident but humble
  • Clear and direct

Tone (Adaptive)

How voice adapts to context:

  • Error messages: Apologetic, helpful
  • Success messages: Encouraging, celebratory
  • Marketing: Enthusiastic, persuasive
  • Documentation: Clear, instructional
  • Support: Empathetic, solution-focused

Voice Dimensions

1. Formality Spectrum

Formal ←→ Casual

Formal:

"We appreciate your business and look forward to serving you."

Casual:

"Thanks for choosing us! We're excited to work with you."

Choose based on:

  • Industry norms
  • Audience expectations
  • Context (legal vs. social)

2. Enthusiasm Spectrum

Reserved ←→ Enthusiastic

Reserved:

"Your account has been created successfully."

Enthusiastic:

"Welcome aboard! Your account is ready to go! 🎉"

Choose based on:

  • Moment significance
  • User emotional state
  • Brand personality

3. Expertise Spectrum

Educational ←→ Expert

Educational:

"Let's walk through this step by step. First, click the 
'Settings' button in the top right corner."

Expert:

"Navigate to Settings > Advanced > API Configuration."

Choose based on:

  • User expertise level
  • Content complexity
  • Context (onboarding vs. advanced docs)

Tone Guidelines by Context

1. Marketing Copy

Characteristics:

  • Enthusiastic and persuasive
  • Benefit-focused
  • Action-oriented
  • Emotionally engaging

Example:

"Transform your workflow in minutes, not months. Join 10,000+ 
teams who've already made the switch."

2. Product Documentation

Characteristics:

  • Clear and instructional
  • Step-by-step
  • Neutral tone
  • Technically accurate

Example:

"To configure authentication:
1. Navigate to Settings > Security
2. Click 'Add Authentication Method'
3. Select your preferred provider"

3. Error Messages

Characteristics:

  • Apologetic but not overly so
  • Explain what happened
  • Provide clear next steps
  • Never blame the user

Bad:

"Error: Invalid input. Try again."

Good:

"We couldn't process your request because the email format 
isn't valid. Please check and try again."

4. Success Messages

Characteristics:

  • Positive and encouraging
  • Confirm what happened
  • Suggest next steps
  • Celebrate wins

Example:

"Great! Your changes have been saved. Ready to publish?"

5. Support Communication

Characteristics:

  • Empathetic and understanding
  • Solution-focused
  • Patient and helpful
  • Personalized

Example:

"I understand how frustrating this must be. Let's get this 
sorted out for you. Can you tell me what you see when you 
click the 'Export' button?"

6. Onboarding

Characteristics:

  • Welcoming and encouraging
  • Educational without overwhelming
  • Progressive disclosure
  • Celebrate small wins

Example:

"Welcome! Let's get you set up in 3 quick steps. 
First, let's create your workspace."

Writing Principles

1. Be Clear and Concise

Before:

"In order to facilitate the process of account creation, 
it is necessary for you to provide your email address."

After:

"Enter your email to create your account."

2. Use Active Voice

Passive:

"Your password has been reset by our system."

Active:

"We've reset your password."

3. Write for Humans

Robotic:

"Operation completed successfully. Proceed to next step."

Human:

"All set! What would you like to do next?"

4. Be Inclusive

Exclusive:

"Hey guys, check out our new feature!"

Inclusive:

"Check out our new feature!"

5. Avoid Jargon

Jargon-heavy:

"Leverage our API to synergize your tech stack."

Clear:

"Connect our API to your existing tools."

Emotional Tone Mapping

User Emotional State → Appropriate Tone

User is frustrated → Empathetic, solution-focused

"I know this is frustrating. Let's fix this together."

User achieved something → Celebratory, encouraging

"Awesome work! You've completed your first project."

User is confused → Patient, educational

"No worries! Let me break this down for you."

User made an error → Helpful, non-judgmental

"Looks like there's a small issue. Here's how to fix it."

User is new → Welcoming, supportive

"Welcome! We're here to help you get started."

Brand Voice Examples

Example 1: Tech Startup (Friendly, Modern)

Voice: Approachable, innovative, helpful
Tone variations:
- Marketing: "Build amazing things, faster"
- Error: "Oops! Something went wrong. Let's try that again."
- Success: "Nice! You're all set."

Example 2: Enterprise SaaS (Professional, Trustworthy)

Voice: Professional, reliable, expert
Tone variations:
- Marketing: "Enterprise-grade security you can trust"
- Error: "We encountered an issue. Please contact support."
- Success: "Configuration saved successfully."

Example 3: Creative Tool (Inspiring, Playful)

Voice: Creative, inspiring, fun
Tone variations:
- Marketing: "Unleash your creativity"
- Error: "Hmm, that didn't work. Let's try something else!"
- Success: "Beautiful! Your design is ready to share."

Best Practices

  1. Create a voice chart - Document your brand's voice attributes
  2. Use real examples - Show, don't just tell
  3. Consider context - Adapt tone to situation
  4. Be consistent - Use the same voice across channels
  5. Avoid clichés - "Think outside the box," "game-changer"
  6. Use contractions - "We're" not "We are" (unless formal)
  7. Address the user - Use "you" and "your"
  8. Be specific - Concrete details over vague statements
  9. Test with users - Does it resonate?
  10. Update regularly - Voice evolves with your brand

Anti-Patterns

  • ❌ Inconsistent voice - Confuses users about your brand
  • ❌ Overly formal - Creates distance from users
  • ❌ Too casual - May seem unprofessional
  • ❌ Jargon overload - Excludes non-experts
  • ❌ Passive voice - Weakens your message
  • ❌ Blaming users - "You entered the wrong password"
  • ❌ Fake enthusiasm - "Amazing! Incredible! Awesome!" overuse
  • ❌ Corporate speak - "Leverage synergies to optimize"

Voice & Tone Checklist

Before publishing, verify:

  • Does this sound like our brand?
  • Is the tone appropriate for the context?
  • Is it clear and easy to understand?
  • Does it use active voice?
  • Is it free of jargon?
  • Does it address the user directly?
  • Is it inclusive and respectful?
  • Does it match our voice chart?
  • Would I say this to someone in person?
  • Does it help the user accomplish their goal?

References

  • Nicely Said by Nicole Fenton & Kate Kiefer Lee
  • The Voice and Tone Guide by MailChimp
  • Conversational Design by Erika Hall