Guides
v1.0
Guides
Start typing to search…
  1. Initiatives

Best Practices

Learn from successful Tidra users to maximize effectiveness and avoid common pitfalls.

Starting Out

Your First Initiative

Pick something simple:

  • Well-defined change (clear before/after)
  • 5-10 repositories
  • Easy to validate by looking at code
  • Not mission-critical

Good first examples:

  • Add a file
  • Update a single config value
  • Add a documentation section

Avoid for first initiative:

  • Complex refactoring
  • Breaking changes
  • 100+ repositories
  • Changes requiring deep domain knowledge

Build Confidence Gradually

Initiative 1: Simple change, 5-10 repos Initiative 2: Similar change, 20-30 repos Initiative 3: More complex, 20-30 repos Initiative 4: Scale up to 50-100 repos

Each success builds confidence and understanding.

Writing Descriptions

Be Specific

The more specific your description, the better Tidra performs.

Instead of: "Update the config"

Write: "In the config/app.yaml file, update the log_level field from 'debug' to 'info'"

Show Examples

Include before/after examples:

Update GitHub Actions:

Before:
uses: actions/setup-node@v3
with:
  node-version: '16'

After:
uses: actions/setup-node@v4
with:
  node-version: '20'

Reference Documentation

Link to relevant docs:

"Follow the migration guide at [link] for updating the authentication flow"

Test Your Description

Generate on 3-5 repos first, then scale to full scope after validating quality.

Repository Selection

Start with Similar Repos

First initiatives work better on repos that are similar:

  • All Node.js repos
  • All use the same framework
  • All have similar structure

Later, you can mix repo types.

Know Your Repositories

Pick repos you're familiar with for your first initiatives. Makes review easier and faster.

Scale Thoughtfully

Don't jump from 10 repos to 200 repos. Go: 10 → 25 → 50 → 100

Validate quality at each step.

Review Process

Always Review Before Creating PRs

Never skip review, even if you're confident.

Check:

  • Are changes correct?
  • Anything unexpected?
  • All repos handled properly?
  • Complexity estimates reasonable?

Review a Sample

For large initiatives (50+ repos):

  1. Review 5-10 repos in detail
  2. Spot-check another 10-15
  3. Verify edge cases
  4. Then create all PRs

Look for Patterns

If multiple repos have issues, refine your description and regenerate rather than fixing individually.

Managing PRs

Set Expectations with Reviewers

Before creating PRs:

  1. Let reviewers know it's coming
  2. Explain what changed and why
  3. Show them a sample PR
  4. Confirm they'll prioritize reviews

Batch PR Creation

For large initiatives:

  • Create 20-30 PRs at a time
  • Let those get reviewed and merged
  • Then create the next batch

Prevents overwhelming reviewers.

Track and Follow Up

Don't create PRs and forget:

  • Check dashboard daily
  • Follow up on blocked PRs
  • Celebrate merged PRs
  • Address issues quickly

Common Patterns

Configuration Updates

Works well:

  • Updating specific fields in config files
  • Adding new config sections
  • Standardizing config structure

Tips:

  • Be specific about which config file
  • Show exact field paths (e.g., database.connection.port)
  • Mention what to do if file doesn't exist

Documentation

Works well:

  • Adding new sections to existing files
  • Creating new documentation files
  • Updating copyright notices

Tips:

  • Specify location (after intro, before examples)
  • Provide exact content or template
  • Mention formatting preferences

Code Changes

Works well:

  • Updating import statements
  • Replacing deprecated function calls
  • Adding consistent error handling

Tips:

  • Show code examples
  • Mention which files to update (all .py files, all .js files)
  • Specify exceptions if any

What Not to Do

Don't Skip Review

❌ Creating PRs without reviewing generated code ✅ Always review first

Don't Blast 100 Repos Untested

❌ Selecting 100 repos for your first initiative ✅ Start with 5-10, validate, then scale

Don't Be Vague

❌ "Fix the things" ✅ "Update the database connection timeout in config/app.yaml from 30s to 60s"

Don't Mix Multiple Changes

❌ "Update Node version AND add linting AND fix README" ✅ One initiative per change type

Don't Assume Context

❌ "Use the new pattern" ✅ "Replace logger.log() with logger.info() throughout the codebase"

Don't Ignore Failed PRs

❌ Leaving blocked PRs unaddressed ✅ Investigate and resolve quickly

Measuring Success

Good Indicators

✅ 80%+ merge rate ✅ Positive feedback from reviewers ✅ PRs merge within days, not weeks ✅ Changes are accurate and complete ✅ Teams asking to use Tidra for more initiatives

Red Flags

🚩 Less than 50% merge rate - quality issues 🚩 PRs require lots of changes - description was unclear 🚩 Teams avoid reviewing - need better communication 🚩 Changes incorrect - description needs refinement

Team Adoption

Build Champions

Find 2-3 early adopters who:

  • Are enthusiastic about automation
  • Have good initiatives to test
  • Will provide honest feedback
  • Can evangelize success to others

Show ROI

Track and share:

  • Time saved
  • Initiatives completed
  • PRs merged
  • Consistency improved

Start with Easy Wins

Pick initiatives that:

  • Are clearly valuable
  • Have high success rates
  • Take minimal review effort
  • Show immediate impact

Continuous Improvement

Learn from Each Initiative

After each initiative, reflect:

  • What worked well?
  • What could be better?
  • How was the merge rate?
  • What did reviewers say?

Iterate on Descriptions

Save good description patterns:

  • Configurations that work well
  • Code patterns that generate clean results
  • Documentation formats that are clear

Share Knowledge

Document learnings:

  • Good first initiatives
  • Description templates
  • Common pitfalls
  • Success stories

Advanced Tips

Use Initiative Templates

Create templates for common changes:

  • Node version updates
  • Docker base image updates
  • Config standardization
  • Documentation additions

Batch Similar Initiatives

If you have multiple related changes:

  1. Do them sequentially, not simultaneously
  2. Let first batch complete
  3. Then start next batch
  4. Prevents review overwhelm

Coordinate with Teams

For changes affecting multiple teams:

  1. Get buy-in upfront
  2. Share timeline
  3. Set review expectations
  4. Communicate progress

Getting Help

When to Ask for Support

  • Generated code quality is inconsistent
  • Not sure how to describe a change
  • Initiatives taking too long
  • Need help with complex use cases

What to Include

When asking for help:

  • What you're trying to accomplish
  • Your description
  • Sample repo
  • What's not working

Success Story Template

Document your wins:

Initiative: [Name]
Goal: [What you were trying to accomplish]
Scope: [X repositories]
Time Investment: [Hours spent]
Time Saved: [Hours would have taken manually]
ROI: [Savings / Investment]
Merge Rate: [%]
Learnings: [What worked well, what to improve]

Share these with your team and leadership.

Next Steps

Updated about 3 hours ago