docs: task.previousTrace directive Documentation

[rnaidu]

PR Checklist: Improve task.previousTrace Documentation

Summary of Changes

This PR enhances the documentation for the task.previousTrace field to provide explicit guidance on accessing runtime metrics from previous task attempts. The changes address user confusion around field availability and access patterns, particularly for implementing retry logic based on performance metrics.

Key Improvements

• Explicit field listing: Added comprehensive list of commonly used fields available in task.previousTrace
• Naming convention documentation: Clarified the p- naming pattern for percentage fields (workaround for Groovy syntax limitations with %)
• Percentage field guidance: Added clear note on how to access percentage-based metrics
• Enhanced cross-references: Improved links to trace report documentation for deeper exploration

---

Pre-Submission Checklist

• Code Quality

  • Changes follow project style guidelines
  • Code is readable and well-organized
  • No unnecessary comments or debug code

• Documentation

  • Changes are clearly documented
  • Documentation is accurate and up-to-date
  • Examples are provided and tested
  • Cross-references are correct and functional

• Testing

  • Documentation examples are verified to work
  • Field names and access patterns have been validated
  • Naming conventions (pcpupmem) are correctly explained

• Review Readiness

  • PR description is clear and complete
  • Related issues are properly referenced
  • No merge conflicts
  • Commit history is clean and logical

• Completeness

  • All promised changes in description are included
  • No unrelated changes included
  • Links and references are functional

---

Detailed Change Summary

Documentation Enhancements

Aspect	Details
Field Listing	Added explicit enumeration of commonly used fields available in task.previousTrace (e.g., memory usage, CPU metrics)
Naming Convention	Documented pcpupmem pattern as a Groovy workaround for percentage fields (can't use % directly in identifiers)
Usage Guidance	Clarified how to access percentage-based fields in code examples
Cross-References	Improved links to trace report documentation for users needing additional details

Files Modified

• Documentation file for task.previousTrace field reference

Impact

• Users: Will have clearer guidance on implementing retry logic using previous task metrics
• Maintainers: Reduces support questions about field access and availability
• Spot Instance Users: Can now easily implement intelligent retry strategies based on CPU and memory metrics from failed attempts

---

Review Notes

For Reviewers: Please verify that all field names and access patterns match the actual implementation in the codebase. Pay particular attention to:

• Accuracy of listed fields
• Correctness of the pcpupmem naming explanation
• Validity of any code examples provided
• Links to trace documentation are current and accurate

[netlify]

✅ Deploy Preview for nextflow-docs-staging ready!

Name	Link
🔨 Latest commit	c9aa75b
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/69149e9b589ce500081db70f
😎 Deploy Preview	https://deploy-preview-6538--nextflow-docs-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rnaidu-seqera]

Created PR from personal account to add clarification to docs for task.previousTrace directive and accessible metadata fields

[christopher-hakkaart]

I cleaned up the PR so the preview is generated. I've also made suggestions to remove the list and a link that didn't exist, and reduce some of the text. Please check the meaning is retained.

[christopher-hakkaart]

Sorry - I was OoO for a few days and forgot to comment this. This looks good to me now. I'll ask @bentsherman to give it a quick look to make sure everything is correct, then it should be good to merge.