From 8777a9641276a7c8f5853961912925efed36a711 Mon Sep 17 00:00:00 2001
From: Vibhav Bobade <vibhav.bobde@gmail.com>
Date: Sun, 26 Jan 2025 02:29:01 +0530
Subject: [PATCH] docs: parameter substitution precedence

---
 docs/stepactions.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/stepactions.md b/docs/stepactions.md
index 6532eb5b27a..120794278be 100644
--- a/docs/stepactions.md
+++ b/docs/stepactions.md
@@ -136,6 +136,21 @@ spec:
 
 **Note:** If a `Step` declares `params` for an `inlined Step`, it will also lead to a validation error. This is because an `inlined Step` gets its `params` from the `TaskRun`.
 
+#### Parameter Substitution Precedence
+
+When applying parameters to a StepAction, the substitutions are applied in the following order:
+
+1. TaskRun parameter values in step parameters
+2. Parameters from StepAction defaults
+3. Parameters from the step (overwriting any defaults)
+4. Step result replacements
+
+This order ensures that:
+- Step parameters can reference TaskRun parameters
+- StepAction defaults provide fallback values
+- Step-specific parameters take precedence over defaults
+- Step result references are resolved last to allow referencing results from previous steps
+
 ### Emitting Results
 
 A `StepAction` also declares the results that it will emit.